@microteia/console 2.7.0

package/lib/kernel/manifest.js

@@ -0,0 +1,145 @@
+export const KERNEL_DISTRIBUTION_ID = 'com.microteia.kernel';
+/**
+ * O Console mínimo que consegue instalar um pacote montado hoje. Sobe junto com uma mudança que o
+ * pacote PASSA A DEPENDER.
+ *
+ * Em `2.0.0`: o arquivo de configuração de backend na raiz da instalação. Um Console `1.0.0`
+ * desempacotaria este pacote e escreveria a credencial em `.microteia/install/functions/`, que o upgrade
+ * seguinte apaga — recusar é mais barato que isso.
+ *
+ * Em `2.1.0`: as Cloud Functions do ESCRITÓRIO. O pacote carrega o SDK cujo `create function` gera uma
+ * extensão que declara a própria function em `manifest.backend.functions`, e um Console anterior monta
+ * essa function dentro do pacote e nunca a deploya — a extensão fica "Backend pendente" para sempre,
+ * com a mensagem errada ("this kernel package does not contain"), apontando para o lugar errado. Foi
+ * exatamente o que aconteceu quando um `microteia` de PATH, linkado a um Console antigo, provisionou uma
+ * instalação montada por um Console novo: nada no relato dizia que o problema era a ferramenta.
+ */
+export const MINIMUM_CLI_VERSION = '2.1.0';
+export const DEFAULT_FUNCTIONS_REGION = 'southamerica-east1';
+/**
+ * A região padrão do Google, que NÃO é a nossa. Uma instalação fora dela chama as callables por um
+ * host próprio da região, e é lá que a permissão de invocação tem de existir — daí o aviso no
+ * `connect`.
+ */
+export const GOOGLE_DEFAULT_REGION = 'us-central1';
+export const REQUIRED_NODE_VERSION = '22';
+export const KERNEL_COMPONENTS = [
+    { id: 'hosting', path: 'hosting' },
+    { id: 'functions', path: 'functions' },
+    { id: 'firestore.rules', path: 'firestore.rules' },
+    { id: 'firestore.indexes', path: 'firestore.indexes.json' },
+    { id: 'storage.rules', path: 'storage.rules' },
+];
+/**
+ * As armadilhas de projeto novo, que até aqui viviam só como prosa no ARCHITECTURE.md (seção "Ao
+ * criar um ambiente do zero"). Elas viajam NO MANIFESTO porque quem instala não tem o ARCHITECTURE.md
+ * — e porque cada uma delas já custou um diagnóstico errado: a falta do App Engine aparece como um
+ * 404 de autenticação de service agent, que manda procurar no lugar errado.
+ */
+export const MANUAL_PREREQUISITES = [
+    {
+        id: 'billing',
+        title: 'Put the Firebase project on the Blaze (pay as you go) plan',
+        detail: 'This one comes before everything else: Cloud Functions of the 2nd generation do not exist on the '
+            + 'free plan, and neither the App Engine application nor the default Storage bucket can be created '
+            + 'without billing. Firebase console, project settings, Usage and billing. Every other step here '
+            + 'fails until this is done.',
+        optional: false,
+    },
+    {
+        id: 'app-engine',
+        title: 'Create the App Engine application before the first deploy',
+        detail: 'Run: gcloud app create --region=<region> --project=<projectId>. Without it the functions deploy '
+            + 'fails at generateUploadUrl with a 404 about the gcf-admin-robot service agent, which does not '
+            + 'mention App Engine at all. The region is set once and can never be changed — use the same '
+            + 'region as the functions.',
+        optional: false,
+    },
+    {
+        id: 'firestore-location',
+        title: 'Create Firestore in the same region as the functions',
+        detail: 'Firestore triggers do not work across regions. The database location is permanent, so getting '
+            + 'this wrong means recreating the project.',
+        optional: false,
+    },
+    {
+        id: 'storage-bucket',
+        title: 'Set up Cloud Storage for Firebase',
+        detail: 'Firebase console, Storage, "Get Started". Enabling the API is not enough — the default bucket '
+            + 'has to be created, and no CLI command does it. Without it the very first deploy stops on the '
+            + 'storage rules. Documents attached to records and the cold backup of expired audit logs both '
+            + 'live here.',
+        optional: false,
+    },
+    {
+        id: 'auth-provider',
+        title: 'Enable the Google sign-in provider in Firebase Authentication',
+        detail: 'Firebase console, Authentication, Sign-in method. Without it nobody can log in.',
+        optional: false,
+    },
+    {
+        id: 'functions-invoker',
+        title: 'Allow unauthenticated invocation of the callable functions, if your organization blocks it',
+        detail: 'The deploy grants allUsers the roles/run.invoker role on every callable, and the deploy checks '
+            + 'it afterwards. An organization that enforces Domain Restricted Sharing refuses that grant, and '
+            + 'then the application loads but every server call fails in the browser with what looks like a '
+            + 'CORS error. The fix is one command per function, and the deploy prints the exact list: gcloud '
+            + 'run services add-iam-policy-binding <function-name-in-lowercase> --region=<region> '
+            + '--project=<projectId> --member=allUsers --role=roles/run.invoker. Unauthenticated invocation '
+            + 'is not open access: every callable still rejects callers with no signed-in user.',
+        optional: true,
+    },
+    {
+        id: 'audit-ttl',
+        title: 'Enable the Firestore TTL policy on auditLogs.expiresAt',
+        detail: 'Firestore console, TTL, collection auditLogs, field expiresAt. It cannot be declared in code or '
+            + 'rules. Without it audit logs are never expired and grow without bound.',
+        optional: false,
+    },
+];
+/**
+ * Os nomes das Cloud Functions saem de `functions/src/index.ts`, a mesma fonte e o mesmo parse que
+ * `scripts/deployLists.test.ts` já usa para garantir que nenhuma function fique fora dos grupos de
+ * deploy. Reaproveitar a fonte guardada evita criar uma terceira lista para desatualizar.
+ */
+export const exportedFunctionNames = (indexSource) => [...indexSource.matchAll(/export\s*\{([^}]+)\}/g)]
+    .flatMap((match) => match[1].split(','))
+    .map((name) => name.trim())
+    .filter((name) => name !== '');
+/**
+ * As callables são as functions que o NAVEGADOR chama. Elas se distinguem das de gatilho por uma
+ * razão prática: só elas podem ser verificadas de fora, e só nelas a permissão de invocação pública
+ * importa. Sem ela a aplicação abre e toda chamada ao servidor falha — parecendo erro de CORS, que
+ * manda procurar no lugar errado.
+ */
+export const callableFunctionNames = (source) => [...source.matchAll(/export\s+const\s+([a-zA-Z0-9_]+)\s*=\s*onCall\b/g)].map((match) => match[1]);
+/**
+ * Os parâmetros que o backend declara com `defineString`. O `firebase-functions` os valida
+ * GLOBALMENTE, e não por function: um parâmetro sem valor e sem default recusa o deploy de TODAS as
+ * functions, inclusive as que não têm relação nenhuma com ele. Foi assim que um `GOOGLE_GMAIL_TOPIC`
+ * ausente derrubou o deploy de `callAIProxy` numa instalação nova.
+ *
+ * Por isso a lista é DERIVADA do código, e não copiada de um `.env.example` — que já estava
+ * desatualizado quando esta função foi escrita.
+ */
+export const declaredParametersIn = (source) => [...source.matchAll(/defineString\(\s*'([A-Z0-9_]+)'\s*(,\s*\{[^}]*\})?\s*\)/g)].map((match) => ({
+    name: match[1],
+    required: match[2] === undefined || !match[2].includes('default'),
+}));
+/** Comparação de versão suficiente para `minimumCliVersion`: três números, sem pré-lançamento. */
+export const compareVersions = (left, right) => {
+    const a = left.split('.').map((part) => Number.parseInt(part, 10));
+    const b = right.split('.').map((part) => Number.parseInt(part, 10));
+    for (let index = 0; index < 3; index += 1) {
+        const difference = (a[index] || 0) - (b[index] || 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};
+export const parseKernelVersion = (source) => {
+    const match = source.match(/KERNEL_VERSION\s*=\s*'([^']+)'/);
+    if (match === null)
+        throw new Error('KERNEL_VERSION not found in domain/schema/plugin/kernelVersion.ts');
+    return match[1];
+};

package/lib/shared/args.d.ts

@@ -0,0 +1,14 @@
+export interface ParsedArgs {
+    positionals: string[];
+    flags: Map<string, string | true>;
+}
+/**
+ * Parser mínimo, na mesma linha do que `deploy-functions-individually.cjs` já faz à mão: aceita
+ * `--flag`, `--flag valor` e `--flag=valor`. Não há biblioteca de CLI no repositório e este milestone
+ * não é motivo para introduzir uma.
+ */
+export declare const parseArgs: (argv: string[]) => ParsedArgs;
+export declare const flagValue: (args: ParsedArgs, name: string) => string | undefined;
+export declare const hasFlag: (args: ParsedArgs, name: string) => boolean;
+/** Falha cedo e com o nome do que faltou, em vez de deixar o comando descobrir no meio. */
+export declare const requiredFlag: (args: ParsedArgs, name: string) => string;

package/lib/shared/args.js

@@ -0,0 +1,44 @@
+/**
+ * Parser mínimo, na mesma linha do que `deploy-functions-individually.cjs` já faz à mão: aceita
+ * `--flag`, `--flag valor` e `--flag=valor`. Não há biblioteca de CLI no repositório e este milestone
+ * não é motivo para introduzir uma.
+ */
+export const parseArgs = (argv) => {
+    const positionals = [];
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const body = token.slice(2);
+        const equals = body.indexOf('=');
+        if (equals !== -1) {
+            flags.set(body.slice(0, equals), body.slice(equals + 1));
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags.set(body, next);
+            index += 1;
+        }
+        else {
+            flags.set(body, true);
+        }
+    }
+    return { positionals, flags };
+};
+export const flagValue = (args, name) => {
+    const value = args.flags.get(name);
+    return typeof value === 'string' ? value : undefined;
+};
+export const hasFlag = (args, name) => args.flags.has(name);
+/** Falha cedo e com o nome do que faltou, em vez de deixar o comando descobrir no meio. */
+export const requiredFlag = (args, name) => {
+    const value = flagValue(args, name);
+    if (value === undefined || value === '') {
+        throw new Error(`Missing required option --${name}.`);
+    }
+    return value;
+};

package/lib/shared/digest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * O tamanho e a impressão digital de um arquivo, que juntos são a única garantia que um artefato
+ * BAIXADO oferece de ser o que foi empacotado.
+ *
+ * Enquanto o tarball chegava à mão — anexo de e-mail, pendrive, Drive —, o transporte era confiável por
+ * construção e o pacote não carregava hash nenhum. Baixado de uma URL, não é: um download interrompido
+ * produz um `.tgz` menor que o `tar` recusa com uma mensagem sobre formato, e a pessoa vai procurar o
+ * defeito no pacote em vez de na rede.
+ *
+ * O `bytes` vem junto de propósito. Ele não acrescenta segurança nenhuma ao `sha256`, mas é o que
+ * permite dizer "veio pela metade" em vez de "não confere" — e essas duas frases mandam procurar em
+ * lugares diferentes.
+ */
+export interface FileDigest {
+    bytes: number;
+    sha256: string;
+}
+/**
+ * Lê por stream, e não com `readFile`: o tarball do kernel passa de 7 MB e cresce a cada versão, e
+ * carregar o arquivo inteiro na memória para depois descartá-lo não tem motivo.
+ */
+export declare const digestOfFile: (path: string) => Promise<FileDigest>;
+/**
+ * O que está errado num arquivo que devia casar com um digest, em prosa que diz onde procurar.
+ *
+ * Devolve `null` quando confere. A ordem importa: o tamanho é conferido primeiro porque é o caso
+ * comum e o que tem conserto óbvio (baixar de novo), e um `sha256` divergente com o tamanho certo é a
+ * situação grave — ali o arquivo não é o que o índice diz que é.
+ */
+export declare const digestMismatch: (expected: FileDigest, actual: FileDigest) => string | null;

package/lib/shared/digest.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+/**
+ * Lê por stream, e não com `readFile`: o tarball do kernel passa de 7 MB e cresce a cada versão, e
+ * carregar o arquivo inteiro na memória para depois descartá-lo não tem motivo.
+ */
+export const digestOfFile = async (path) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    await new Promise((resolve, reject) => {
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', (error) => reject(error));
+        stream.on('end', () => resolve());
+    });
+    const { size } = await stat(path);
+    return { bytes: size, sha256: hash.digest('hex') };
+};
+/**
+ * O que está errado num arquivo que devia casar com um digest, em prosa que diz onde procurar.
+ *
+ * Devolve `null` quando confere. A ordem importa: o tamanho é conferido primeiro porque é o caso
+ * comum e o que tem conserto óbvio (baixar de novo), e um `sha256` divergente com o tamanho certo é a
+ * situação grave — ali o arquivo não é o que o índice diz que é.
+ */
+export const digestMismatch = (expected, actual) => {
+    if (actual.bytes !== expected.bytes) {
+        return `it has ${actual.bytes} bytes and should have ${expected.bytes} — the download did not finish.`;
+    }
+    if (actual.sha256 !== expected.sha256) {
+        return `its sha256 is ${actual.sha256} and should be ${expected.sha256}.`;
+    }
+    return null;
+};

package/lib/shared/paths.d.ts

@@ -0,0 +1,90 @@
+export declare const repoRoot: string;
+/**
+ * A raiz do CONSOLE: `cli/` dentro do repositório, e a própria pasta do pacote quando ela é montada por
+ * `pack-console`. Vale nos dois porque a profundidade de `shared/` até ela é a mesma (`cli/lib/shared`,
+ * `cli/src/shared` em teste, `<pasta>/lib/shared` no pacote) — o mesmo motivo do cálculo acima.
+ *
+ * É por aqui que o `unpack` acha o `CONSOLE-VERSIONS.md`: o histórico do Console viaja com o binário do
+ * Console, e não com o pacote do kernel. Ao contrário de `repoRoot`, este caminho continua verdadeiro
+ * fora do repositório.
+ */
+export declare const consoleRoot: string;
+/**
+ * A versão do CONSOLE, deliberadamente independente do `version` do produto: ela diz o que a
+ * ferramenta sabe fazer, e é contra ela que o `minimumCliVersion` do manifesto é conferido. Um
+ * pacote novo pode exigir um Console mais novo sem que o número do produto signifique nada aqui.
+ *
+ * Semver do lado da FERRAMENTA: major quando um comando muda de contrato, minor quando ganha
+ * capacidade, patch quando muda o que ele escreve sem que o pacote passe a depender disso. Em
+ * `2.0.0`: o `deploy` deixou de aceitar `--kernel` (o pacote passa a chegar pelo `unpack`), e as
+ * configurações de backend saíram de `.microteia/` para a raiz da instalação — um Console anterior
+ * gravaria a credencial no lugar que o upgrade apaga. `unpack` e `plugin-init` são aditivos e
+ * sozinhos pediriam só o minor. Em `2.0.1`: o `.gitignore` da instalação passa a descartar os
+ * `examples/`, que o `unpack` reescreve e ninguém versiona. Em `2.0.2`: o `AGENTS.md` e o
+ * `AUTHORING.md` que ele escreve passam a cobrar versão, entrada de histórico e teste a cada
+ * alteração de extensão. Em `2.1.0`: as Cloud Functions que o ESCRITÓRIO escreve deixam de ser
+ * montadas e esquecidas — as de `functions/` sobem no `deploy`, as de `extensions/<plugin>/functions/`
+ * sobem pelo provisionamento (e `manifest.backend.functions` pode nomeá-las, que era o que o
+ * `create function` já mandava escrever e o `provision` recusava), cada diretório pode declarar as
+ * próprias dependências npm, e os `defineString` delas entram no `.env.<projectId>`. Em `2.1.1`: o
+ * `extensions/` gerado ganha `npm run sdk:refresh`, porque `npm install` NÃO traz o SDK novo — o
+ * caminho do tarball não leva versão e o lock guarda a impressão digital do anterior, então o npm diz
+ * "up to date" e o escritório segue escrevendo contra um contrato que a instalação não tem mais. Em
+ * `2.1.2`: a recusa de uma function reivindicada passa a nomear as DUAS origens possíveis — o pacote e
+ * o `extensions/<pasta>/functions/` do escritório —, porque dizer só "o pacote não a contém" manda
+ * procurar no lugar errado justamente no caso mais comum. Em `2.1.3`: a montagem deixa os arquivos de
+ * TESTE fora do artefato. O `predeploy` do pacote compila `custom/` com o `tsc`, e um `import` de
+ * `vitest` ali é `Cannot find module` — a compilação falha e leva embora o deploy de TODAS as functions,
+ * não só das da extensão que trouxe o teste. O `AGENTS.md` manda escrever teste ao lado da function;
+ * era este lado que faltava. Em `2.1.4`: o `unpack` preserva `functions/node_modules` MOVENDO em vez de
+ * copiando — o `cp` recursivo de ~250 pacotes estourava o limite de descritores do processo no macOS
+ * (`ENFILE: file table overflow`), de forma intermitente e apontando um diretório qualquer de dentro de
+ * uma dependência. A cópia nunca teve para que existir: a origem é apagada em seguida. Em `2.1.5`: o carimbo
+ * `backendState.appliedAt` passou a ser gravado como DATA (`timestampValue`) e não como texto — o
+ * `stringValue` chegava à tela como string com o tipo de `Date`, e derrubava o botão de atualizar a
+ * extensão na gravação seguinte. Em `2.2.0`: o `sourceFile` de uma view passa a aceitar LISTA, e o
+ * `AUTHORING.md` que este Console escrevia ganhou a seção que explica a fusão. Em `2.3.0`: ele deixa de
+ * escrever documento nenhum em `extensions/`. `AGENTS.md`, `AUTHORING.md`, `tsconfig.json` e `.mcp.json`
+ * descrevem o que o KERNEL sabe fazer, e passaram para o SDK, que viaja no mesmo pacote daquelas
+ * capacidades — enquanto saíam daqui, um Console de duas versões atrás escrevia, em silêncio, a
+ * documentação de outro contrato. O `plugin-init` semeia e delega; o `unpack` traz o SDK novo e manda
+ * ele reescrever, que é o gatilho que não existia: aqueles arquivos eram escritos UMA vez e nunca mais.
+ * O refresh do SDK perdeu o `--no-save` que tinha: com ele o pacote novo é extraído e o
+ * `package-lock.json` fica no anterior, então o `npm install` seguinte reinstala o antigo e desfaz o
+ * refresh — em silêncio, que é justamente o que ele existe para evitar. E instala pelo caminho RELATIVO
+ * ao diretório, porque o npm reescreve a dependência com o caminho que recebe, e um absoluto no
+ * `package.json` mataria a portabilidade que o relativo existe para dar.
+ *
+ * Em `2.4.0`: o índice composto de uma extensão passa a sobreviver à troca de kernel. Ele era registrado
+ * só no `firestore.indexes.json` de dentro de `.microteia/install/`, que o `unpack` apaga inteiro — e o
+ * pacote traz apenas a baseline, porque o que uma extensão reivindica sai dela para não viajar até quem
+ * não a instalou. O resultado era o `microteia deploy` PERGUNTANDO, no meio de um upgrade, se podia
+ * apagar do projeto o índice de toda extensão instalada; e o aviso de índice órfão, que lia a mesma
+ * memória, emudecia justamente ali. A memória mudou para `backend.indexes` do `microteia.yaml`, na raiz,
+ * e o `unpack` devolve ao arquivo o que ela lembra antes de qualquer comando poder publicá-lo. No mesmo
+ * passo, o `kernel.version` do `microteia.yaml` deixa de mentir entre desempacotar e publicar: ele é
+ * gravado pelo `unpack`, e `kernel.deployed` — novo — é o que o `deploy` carimba. E `--version` responde
+ * as três, porque quem pergunta a versão quase nunca quer a da ferramenta.
+ *
+ * Em `2.5.0`: a function que ficou para trás numa região abandonada deixa de travar o deploy em
+ * silêncio. Trocar a região de uma Cloud Function não move nada — o Firebase cria a nova e deixa a
+ * antiga —, e a partir dali o `firebase deploy --only functions:<nome>` recusa: o filtro `--only`
+ * casa por id e ignora região, então a cópia velha entra no plano como algo a apagar, e apagar exige
+ * uma confirmação que um deploy sem terminal não tem como dar. O `deploy` e o `provision` agora
+ * conferem isso ANTES de subir, e `--prune` remove as cópias. Junto vieram as duas razões de o
+ * defeito ter levado tanto tempo para ser lido: o motivo impresso era o aviso de descontinuação do
+ * Runtime Config — a única coisa que o `firebase` manda pelo stderr, enquanto o erro sai pelo stdout,
+ * e a busca era pela última linha casada —, e a segunda passada repetia as oito functions para
+ * receber palavra por palavra a mesma recusa. O aviso virou UMA nota no fim, o motivo passou a ser
+ * escolhido por quanto informa, e a repetição ficou só para a falha que repetir pode consertar.
+ *
+ * Ela NÃO acompanha o `version` do produto, e não é obrigada a andar junto do `MINIMUM_CLI_VERSION`:
+ * este último só se move quando o PACOTE passa a depender de algo que o Console faz.
+ *
+ * **A narrativa acima para na `2.5.0`, e é de propósito.** De `2.6.0` em diante a entrada de cada
+ * versão é escrita em `cli/CONSOLE-VERSIONS.md` — em inglês, no modelo do git —, porque aquele arquivo
+ * viaja com o Console e chega à raiz da instalação a cada `unpack`. Um histórico dentro de um comentário
+ * 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.0";

package/lib/shared/paths.js

@@ -0,0 +1,97 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * A raiz do repositório, a partir da localização deste módulo. A profundidade é a mesma compilado
+ * (`cli/lib/shared/`) e em teste (`cli/src/shared/`), então um único cálculo serve aos dois.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+export const repoRoot = resolve(here, '..', '..', '..');
+/**
+ * A raiz do CONSOLE: `cli/` dentro do repositório, e a própria pasta do pacote quando ela é montada por
+ * `pack-console`. Vale nos dois porque a profundidade de `shared/` até ela é a mesma (`cli/lib/shared`,
+ * `cli/src/shared` em teste, `<pasta>/lib/shared` no pacote) — o mesmo motivo do cálculo acima.
+ *
+ * É por aqui que o `unpack` acha o `CONSOLE-VERSIONS.md`: o histórico do Console viaja com o binário do
+ * Console, e não com o pacote do kernel. Ao contrário de `repoRoot`, este caminho continua verdadeiro
+ * fora do repositório.
+ */
+export const consoleRoot = resolve(here, '..', '..');
+/**
+ * A versão do CONSOLE, deliberadamente independente do `version` do produto: ela diz o que a
+ * ferramenta sabe fazer, e é contra ela que o `minimumCliVersion` do manifesto é conferido. Um
+ * pacote novo pode exigir um Console mais novo sem que o número do produto signifique nada aqui.
+ *
+ * Semver do lado da FERRAMENTA: major quando um comando muda de contrato, minor quando ganha
+ * capacidade, patch quando muda o que ele escreve sem que o pacote passe a depender disso. Em
+ * `2.0.0`: o `deploy` deixou de aceitar `--kernel` (o pacote passa a chegar pelo `unpack`), e as
+ * configurações de backend saíram de `.microteia/` para a raiz da instalação — um Console anterior
+ * gravaria a credencial no lugar que o upgrade apaga. `unpack` e `plugin-init` são aditivos e
+ * sozinhos pediriam só o minor. Em `2.0.1`: o `.gitignore` da instalação passa a descartar os
+ * `examples/`, que o `unpack` reescreve e ninguém versiona. Em `2.0.2`: o `AGENTS.md` e o
+ * `AUTHORING.md` que ele escreve passam a cobrar versão, entrada de histórico e teste a cada
+ * alteração de extensão. Em `2.1.0`: as Cloud Functions que o ESCRITÓRIO escreve deixam de ser
+ * montadas e esquecidas — as de `functions/` sobem no `deploy`, as de `extensions/<plugin>/functions/`
+ * sobem pelo provisionamento (e `manifest.backend.functions` pode nomeá-las, que era o que o
+ * `create function` já mandava escrever e o `provision` recusava), cada diretório pode declarar as
+ * próprias dependências npm, e os `defineString` delas entram no `.env.<projectId>`. Em `2.1.1`: o
+ * `extensions/` gerado ganha `npm run sdk:refresh`, porque `npm install` NÃO traz o SDK novo — o
+ * caminho do tarball não leva versão e o lock guarda a impressão digital do anterior, então o npm diz
+ * "up to date" e o escritório segue escrevendo contra um contrato que a instalação não tem mais. Em
+ * `2.1.2`: a recusa de uma function reivindicada passa a nomear as DUAS origens possíveis — o pacote e
+ * o `extensions/<pasta>/functions/` do escritório —, porque dizer só "o pacote não a contém" manda
+ * procurar no lugar errado justamente no caso mais comum. Em `2.1.3`: a montagem deixa os arquivos de
+ * TESTE fora do artefato. O `predeploy` do pacote compila `custom/` com o `tsc`, e um `import` de
+ * `vitest` ali é `Cannot find module` — a compilação falha e leva embora o deploy de TODAS as functions,
+ * não só das da extensão que trouxe o teste. O `AGENTS.md` manda escrever teste ao lado da function;
+ * era este lado que faltava. Em `2.1.4`: o `unpack` preserva `functions/node_modules` MOVENDO em vez de
+ * copiando — o `cp` recursivo de ~250 pacotes estourava o limite de descritores do processo no macOS
+ * (`ENFILE: file table overflow`), de forma intermitente e apontando um diretório qualquer de dentro de
+ * uma dependência. A cópia nunca teve para que existir: a origem é apagada em seguida. Em `2.1.5`: o carimbo
+ * `backendState.appliedAt` passou a ser gravado como DATA (`timestampValue`) e não como texto — o
+ * `stringValue` chegava à tela como string com o tipo de `Date`, e derrubava o botão de atualizar a
+ * extensão na gravação seguinte. Em `2.2.0`: o `sourceFile` de uma view passa a aceitar LISTA, e o
+ * `AUTHORING.md` que este Console escrevia ganhou a seção que explica a fusão. Em `2.3.0`: ele deixa de
+ * escrever documento nenhum em `extensions/`. `AGENTS.md`, `AUTHORING.md`, `tsconfig.json` e `.mcp.json`
+ * descrevem o que o KERNEL sabe fazer, e passaram para o SDK, que viaja no mesmo pacote daquelas
+ * capacidades — enquanto saíam daqui, um Console de duas versões atrás escrevia, em silêncio, a
+ * documentação de outro contrato. O `plugin-init` semeia e delega; o `unpack` traz o SDK novo e manda
+ * ele reescrever, que é o gatilho que não existia: aqueles arquivos eram escritos UMA vez e nunca mais.
+ * O refresh do SDK perdeu o `--no-save` que tinha: com ele o pacote novo é extraído e o
+ * `package-lock.json` fica no anterior, então o `npm install` seguinte reinstala o antigo e desfaz o
+ * refresh — em silêncio, que é justamente o que ele existe para evitar. E instala pelo caminho RELATIVO
+ * ao diretório, porque o npm reescreve a dependência com o caminho que recebe, e um absoluto no
+ * `package.json` mataria a portabilidade que o relativo existe para dar.
+ *
+ * Em `2.4.0`: o índice composto de uma extensão passa a sobreviver à troca de kernel. Ele era registrado
+ * só no `firestore.indexes.json` de dentro de `.microteia/install/`, que o `unpack` apaga inteiro — e o
+ * pacote traz apenas a baseline, porque o que uma extensão reivindica sai dela para não viajar até quem
+ * não a instalou. O resultado era o `microteia deploy` PERGUNTANDO, no meio de um upgrade, se podia
+ * apagar do projeto o índice de toda extensão instalada; e o aviso de índice órfão, que lia a mesma
+ * memória, emudecia justamente ali. A memória mudou para `backend.indexes` do `microteia.yaml`, na raiz,
+ * e o `unpack` devolve ao arquivo o que ela lembra antes de qualquer comando poder publicá-lo. No mesmo
+ * passo, o `kernel.version` do `microteia.yaml` deixa de mentir entre desempacotar e publicar: ele é
+ * gravado pelo `unpack`, e `kernel.deployed` — novo — é o que o `deploy` carimba. E `--version` responde
+ * as três, porque quem pergunta a versão quase nunca quer a da ferramenta.
+ *
+ * Em `2.5.0`: a function que ficou para trás numa região abandonada deixa de travar o deploy em
+ * silêncio. Trocar a região de uma Cloud Function não move nada — o Firebase cria a nova e deixa a
+ * antiga —, e a partir dali o `firebase deploy --only functions:<nome>` recusa: o filtro `--only`
+ * casa por id e ignora região, então a cópia velha entra no plano como algo a apagar, e apagar exige
+ * uma confirmação que um deploy sem terminal não tem como dar. O `deploy` e o `provision` agora
+ * conferem isso ANTES de subir, e `--prune` remove as cópias. Junto vieram as duas razões de o
+ * defeito ter levado tanto tempo para ser lido: o motivo impresso era o aviso de descontinuação do
+ * Runtime Config — a única coisa que o `firebase` manda pelo stderr, enquanto o erro sai pelo stdout,
+ * e a busca era pela última linha casada —, e a segunda passada repetia as oito functions para
+ * receber palavra por palavra a mesma recusa. O aviso virou UMA nota no fim, o motivo passou a ser
+ * escolhido por quanto informa, e a repetição ficou só para a falha que repetir pode consertar.
+ *
+ * Ela NÃO acompanha o `version` do produto, e não é obrigada a andar junto do `MINIMUM_CLI_VERSION`:
+ * este último só se move quando o PACOTE passa a depender de algo que o Console faz.
+ *
+ * **A narrativa acima para na `2.5.0`, e é de propósito.** De `2.6.0` em diante a entrada de cada
+ * versão é escrita em `cli/CONSOLE-VERSIONS.md` — em inglês, no modelo do git —, porque aquele arquivo
+ * viaja com o Console e chega à raiz da instalação a cada `unpack`. Um histórico dentro de um comentário
+ * 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.0';

package/lib/shared/run.d.ts

@@ -0,0 +1,28 @@
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface CaptureResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * O erro carrega o comando e a saída para que a falha seja legível sem ter que reproduzir a mão.
+ * O `deploy-functions-individually.cjs` roda os deploys com `stdio: 'pipe'` e descarta a saída no
+ * catch — a falha vira só "❌ Falha no deploy de X", e descobrir o motivo exige rodar de novo. Aqui
+ * a saída capturada é sempre reanexada ao erro.
+ */
+export interface CommandError extends Error {
+    command: string;
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Executa herdando stdio: a saída do `firebase` e do `npm` vai direto para o terminal de quem instala. */
+export declare const run: (command: string, args: string[], options?: RunOptions) => Promise<void>;
+/** Executa capturando a saída, para quando ela é DADO (`firebase apps:sdkconfig --json`). */
+export declare const capture: (command: string, args: string[], options?: RunOptions) => Promise<CaptureResult>;
+/** Como `capture`, mas exige sucesso. Use quando a saída é dado e a falha é fatal. */
+export declare const captureOrThrow: (command: string, args: string[], options?: RunOptions) => Promise<string>;
+export declare const sleep: (seconds: number) => Promise<void>;

package/lib/shared/run.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+const commandLine = (command, args) => [command, ...args].join(' ');
+const commandError = (command, args, code, stdout, stderr) => {
+    const detail = [stderr.trim(), stdout.trim()].filter((part) => part !== '').join('\n');
+    const error = new Error(`Command failed (exit ${code}): ${commandLine(command, args)}${detail === '' ? '' : `\n${detail}`}`);
+    error.command = commandLine(command, args);
+    error.code = code;
+    error.stdout = stdout;
+    error.stderr = stderr;
+    return error;
+};
+/** Executa herdando stdio: a saída do `firebase` e do `npm` vai direto para o terminal de quem instala. */
+export const run = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env === undefined ? process.env : { ...process.env, ...options.env },
+        stdio: 'inherit',
+    });
+    child.on('error', (error) => reject(error));
+    child.on('close', (code) => {
+        if (code === 0)
+            resolve();
+        else
+            reject(commandError(command, args, code ?? -1, '', ''));
+    });
+});
+/** Executa capturando a saída, para quando ela é DADO (`firebase apps:sdkconfig --json`). */
+export const capture = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env === undefined ? process.env : { ...process.env, ...options.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+    child.on('error', (error) => reject(error));
+    child.on('close', (code) => resolve({ code: code ?? -1, stdout, stderr }));
+});
+/** Como `capture`, mas exige sucesso. Use quando a saída é dado e a falha é fatal. */
+export const captureOrThrow = async (command, args, options = {}) => {
+    const result = await capture(command, args, options);
+    if (result.code !== 0) {
+        throw commandError(command, args, result.code, result.stdout, result.stderr);
+    }
+    return result.stdout;
+};
+export const sleep = (seconds) => new Promise((resolve) => { setTimeout(resolve, seconds * 1000); });

package/lib/shared/ui.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Saída do Console. Ela é lida por QUEM INSTALA — que pode não ser quem empacotou, e pode não estar
+ * no Brasil —, então é em inglês, pela mesma razão que o diagnóstico de boot em
+ * `infrastructure/firebase/config.ts` é. Comentário continua em português.
+ */
+export declare const heading: (text: string) => void;
+export declare const info: (text: string) => void;
+export declare const step: (index: number, total: number, text: string) => void;
+/**
+ * Uma linha de "começando", para o passo que demora. Existe porque só imprimir o resultado deixa a
+ * saída MUDA justamente durante a espera: o primeiro deploy de function leva minutos (o Firebase
+ * provisiona build e Artifact Registry na primeira vez), e quem instala não tem como distinguir
+ * "trabalhando" de "travado".
+ *
+ * É uma linha inteira, e não um `\r` reescrito depois: o retorno de carro fica bonito no terminal e
+ * vira lixo no arquivo de log — que é justamente o que se cola num pedido de ajuda.
+ */
+export declare const pending: (text: string) => void;
+export declare const success: (text: string) => void;
+export declare const warn: (text: string) => void;
+export declare const failure: (text: string) => void;
+export declare const bullets: (items: string[]) => void;
+export declare const blank: () => void;

package/lib/shared/ui.js

@@ -0,0 +1,43 @@
+/**
+ * Saída do Console. Ela é lida por QUEM INSTALA — que pode não ser quem empacotou, e pode não estar
+ * no Brasil —, então é em inglês, pela mesma razão que o diagnóstico de boot em
+ * `infrastructure/firebase/config.ts` é. Comentário continua em português.
+ */
+const RULE = '─'.repeat(64);
+export const heading = (text) => {
+    process.stdout.write(`\n${text}\n${RULE}\n`);
+};
+export const info = (text) => {
+    process.stdout.write(`${text}\n`);
+};
+export const step = (index, total, text) => {
+    process.stdout.write(`\n[${index}/${total}] ${text}\n`);
+};
+/**
+ * Uma linha de "começando", para o passo que demora. Existe porque só imprimir o resultado deixa a
+ * saída MUDA justamente durante a espera: o primeiro deploy de function leva minutos (o Firebase
+ * provisiona build e Artifact Registry na primeira vez), e quem instala não tem como distinguir
+ * "trabalhando" de "travado".
+ *
+ * É uma linha inteira, e não um `\r` reescrito depois: o retorno de carro fica bonito no terminal e
+ * vira lixo no arquivo de log — que é justamente o que se cola num pedido de ajuda.
+ */
+export const pending = (text) => {
+    process.stdout.write(`  ...   ${text}\n`);
+};
+export const success = (text) => {
+    process.stdout.write(`  ok    ${text}\n`);
+};
+export const warn = (text) => {
+    process.stderr.write(`  warn  ${text}\n`);
+};
+export const failure = (text) => {
+    process.stderr.write(`  fail  ${text}\n`);
+};
+export const bullets = (items) => {
+    for (const item of items)
+        process.stdout.write(`  - ${item}\n`);
+};
+export const blank = () => {
+    process.stdout.write('\n');
+};

package/lib/vendor/authoringGuide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `AUTHORING.md` — o manual de quem escreve extensão, e o contraponto do `ARCHITECTURE.md`: aquele
+ * explica o kernel a quem o altera, este explica o CONTRATO a quem nunca vai vê-lo.
+ *
+ * Em inglês, e não por preferência: é superfície de produto, entregue a escritórios em qualquer lugar.
+ * A regra de idioma do repositório é exatamente essa — o produto fala inglês porque tem de poder falar
+ * qualquer idioma; o português é a nossa comunicação interna.
+ *
+ * Mora no Console (e não como arquivo `.md` solto) para que a versão do kernel e a lista de pontos de
+ * extensão sejam CARIMBADAS no texto: um manual que fala de um contrato diferente do instalado é pior
+ * que manual nenhum.
+ */
+export interface ExtensionPointRow {
+    id: string;
+    apiVersion: string;
+    allowedImplKinds: string[];
+    multiple: boolean;
+}
+export declare const authoringGuide: (kernelVersion: string, points: ExtensionPointRow[], hostModules: string[]) => string;