@microteia/console 2.7.0

package/CONSOLE-VERSIONS.md

@@ -0,0 +1,85 @@
+# Microteia Console — changelog
+
+> Technical history of the Console — the command that installs, upgrades and publishes Microteia in a
+> Firebase project. Newest first, one entry per `CLI_VERSION`.
+>
+> The Console is versioned and distributed **separately** from the platform: `CLI_VERSION` does not
+> follow the package's `version`, and a package states the oldest Console it can be installed by
+> (`minimumCliVersion`). So the two histories are two files. The platform's is `KERNEL-VERSIONS.md`,
+> beside this one.
+>
+> **This file travels with the Console**, and `microteia unpack` replaces the copy next to your
+> `microteia.yaml` on every run. Do not edit that copy.
+>
+> Semver on the TOOL's side: major when a command changes contract, minor when it gains a capability,
+> patch when what it writes changes without the package coming to depend on it.
+
+<!-- A new entry goes here, above the previous ones, in this format:
+
+#### [9.9.9] — YYYY-MM-DD
+
+- feat(command): what the command now does.
+- fix(command): what was broken, and what it did to whoever hit it.
+-->
+
+#### [2.7.0] — 2026-08-24
+
+- feat(unpack): `--version latest` and `--version <x.y.z>` take a platform version from the published
+  catalog — read it, download it, verify its size and sha256, and cache it under `~/.microteia/cache`,
+  outside the installation because `.microteia/` is deleted whole on every kernel swap. `--kernel
+  <package>.tgz` is unchanged and is not legacy: while installing depends on a download, a machine with
+  no access to the catalog cannot install anything, and the installation already depends on enough that
+  is not ours. A cache entry whose digest does not match is deleted and fetched again, so there is no
+  flag to bypass it — the person who would need one is the one who would not think to pass it.
+- fix(unpack): the refusal by `minimumCliVersion` happens BEFORE the previous install is touched.
+  Extracting and swapping were one step, and the swap came before the manifest was read: a package
+  demanding a newer Console deleted the `install/` of the version that worked and only then refused,
+  leaving the installation with no kernel at all — because of a check that exists precisely so that
+  nothing would happen. It is now extract, verify, then commit, and a refusal removes the staging it
+  opened.
+- feat(publish): releases what `pack` and `pack-console` built — assets to a releases-only repository
+  through `gh`, the Console to npm, and the catalog last. That order is the decision: a catalog pointing
+  at a file that did not upload breaks every installation asking for `latest`, while a file the catalog
+  does not yet mention breaks nothing. An interrupted publish is resumed rather than refused, since
+  refusing would leave deleting the release by hand as the only way out. It does not build — `pack` is
+  what runs the quality gate — it re-derives the tarball's sha256 instead of trusting the manifest
+  beside it, and it refuses a version already in the catalog: a released version is never rewritten.
+- feat(pack-console): the packed folder is publishable as `@microteia/console`, so an office installs
+  the Console with `npm i -g @microteia/console` or runs it with `npx`. This closes a chicken-and-egg:
+  while the Console itself had to be downloaded from somewhere, someone had to download the downloader,
+  and the first step of installing was a folder received by e-mail and an `ln -s` written by hand. The
+  registry already provides the versioned URL, the lockfile fingerprint, the CDN and `npm outdated` that
+  a channel would have had to reimplement. `CONSOLE-VERSIONS.md` is in `files` for a reason that is not
+  documentation: `unpack` reads it beside the running binary, and outside `files` it does not exist in a
+  global install.
+- feat(--version): says when a newer kernel is published, and the lookup is injected rather than called
+  from the report. `--version` is the first command run when something is odd and the answer people paste
+  into a request for help; it answers about the installation, so on a machine with no network it answers
+  the same.
+- feat(publish): `--otp <code>` reaches `npm publish`, and a refused publish prints what the registry
+  requires. The registry accepts neither a plain `npm login` token nor an account without 2FA, so
+  without a way through the command it was unusable: it called `npm publish`, got a 403, and the only
+  way out was running `npm` by hand — which skips the changelog check this command exists to make. The
+  note is printed on ANY failure and does not claim the cause: `npm`'s output goes straight to the
+  terminal, so what reaches the catch is "Command failed (exit 1)" and nothing else. A first version
+  looked for "2fa" in that text and never once printed.
+- fix(connect): the last line printed `microteia deploy --kernel <pkg>.tgz`. That flag left `deploy` in
+  `2.0.0`, so the line had been sending whoever just connected straight into a refusal — on the command
+  right after the one that worked. It now prints `unpack --version latest` and `deploy`.
+
+#### [2.6.0] — 2026-08-23
+
+- feat(unpack): writes `KERNEL-VERSIONS.md` and `CONSOLE-VERSIONS.md` into the installation root, and
+  replaces both on every run. The first is copied out of the unpacked package, the second comes from
+  the Console binary that is running — each history written by the artifact it belongs to, which is
+  the only way neither can describe a version that is not there.
+- feat(pack-console): the packed folder carries `CONSOLE-VERSIONS.md`, and packaging refuses a
+  `CLI_VERSION` this file has no entry for.
+- docs(unpack): the generated `MICROTEIA.md` and the seeded `README.md` list both changelogs in the
+  directory map, so the files are found without being looked for.
+- docs(readme): the packed README no longer tells you to run `microteia deploy --kernel <pkg>.tgz`.
+  That flag was removed in `2.0.0` — the package arrives through `unpack` — and the line had been
+  sending whoever installed to a refusal ever since.
+
+Entries before `2.6.0` are in the `CLI_VERSION` block of `cli/src/shared/paths.ts`, in the language of
+the team that wrote them. They stay there; this file is where the history continues.

package/README.md

@@ -0,0 +1,64 @@
+# Microteia Console 2.7.0
+
+Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
+what it needs are command-line tools that are already on the machine, listed at the bottom.
+
+## Installing it
+
+    npm i -g @microteia/console
+    microteia --help
+
+Or run it without installing anything:
+
+    npx @microteia/console --help
+
+Where npm's global prefix belongs to root — Node installed system-wide under `/usr/local` — the global
+install fails with EACCES. Point npm at a prefix of your own instead of reaching for sudo, which would
+write root-owned files that then need sudo to remove:
+
+    npm config set prefix ~/.npm-global
+    export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc
+
+This folder also runs as it is, with no npm at all:
+
+    node lib/index.js --help
+
+## Using it
+
+    microteia init --name "<office>"
+    microteia connect --project <your-firebase-project-id>
+    microteia unpack --version latest
+    microteia deploy
+
+`connect` prints everything that has to be prepared in the Firebase project first — start with the
+Blaze plan, since nothing else can be created without it.
+
+`unpack --version` reads the published catalog, downloads the version and checks its sha256 before
+touching what is installed. On a machine that cannot reach the catalog, name a file you already have:
+
+    microteia unpack --kernel <microteia-kernel-x.y.z>.tgz
+
+`microteia --version` answers what is installed here, and says so when a newer kernel is published.
+
+Later, whenever an office installs an extension that needs server-side resources, run:
+
+    microteia provision
+
+The extension shows "Backend pending" in the application until you do, and stays out of the menu.
+
+## What has to exist on this machine
+
+| Tool          | Used for                                                       |
+| ------------- | -------------------------------------------------------------- |
+| Node.js 22+   | running this Console (newer is fine; the functions' own runtime is pinned to 22) |
+| `firebase`    | every deploy — authenticate with `firebase login` first          |
+| `npm`, `tar` | installing the functions' dependencies and unpacking the kernel  |
+| `gcloud`      | creating the App Engine application, and reading which extensions an office installed (`gcloud auth login`) |
+
+The `pack` and `publish` commands in here build and release the platform itself, and only work inside
+the Microteia repository.
+
+## What changed in this Console
+
+`CONSOLE-VERSIONS.md`, in this folder. `unpack` copies it into the installation it manages, beside the
+platform's own `KERNEL-VERSIONS.md` — each history travels with the artifact it describes.

package/lib/console/backendEnv.d.ts

@@ -0,0 +1,52 @@
+import type { BackendParameter } from '../kernel/manifest.js';
+/**
+ * As configurações de backend são do ESCRITÓRIO, e por isso moram ao lado do `microteia.yaml` — não
+ * dentro de `.microteia/`.
+ *
+ * Elas moravam lá dentro, e o resultado era perda de dado: o `deploy` substitui o pacote por inteiro
+ * (`rm -rf install` e renomeia o staging), preservando explicitamente só `functions/custom` e
+ * `functions/node_modules`. Uma credencial preenchida à mão em
+ * `.microteia/install/functions/.env.<projectId>` era apagada no deploy seguinte, e o
+ * `ensureBackendEnv` a recriava VAZIA — com o agravante de que a impressão digital deixava de bater, o
+ * provisionamento marcava as functions como obsoletas e as redeployava com a string vazia. Ou seja: o
+ * mecanismo escrito para detectar valor faltando passava a ser a causa dele.
+ *
+ * O diretório do `microteia.yaml` é o repositório de quem mantém a instalação: é onde ficam as
+ * extensões que ele escreve (`extensions/`) e o registro do ambiente. `.microteia/` é descartável por
+ * definição — tudo ali se refaz do tarball mais um `connect` —, e nada que uma pessoa digita pode
+ * depender de sobreviver a isso.
+ *
+ * O arquivo que o `firebase-functions` lê continua tendo de estar em `install/functions/`, então ele é
+ * uma CÓPIA, escrita no deploy. A fonte é a da raiz.
+ */
+/** O arquivo que o escritório edita. O nome leva o projeto: uma instalação, um projeto Firebase. */
+export declare const officeEnvName: (projectId: string) => string;
+export declare const officeEnvPath: (root: string, projectId: string) => string;
+export interface EnsureEnvResult {
+    path: string;
+    created: boolean;
+    added: string[];
+}
+/**
+ * Garante que o arquivo existe e declara todo parâmetro do pacote.
+ *
+ * ACRESCENTA o que falta, nunca reescreve: um parâmetro novo numa versão nova do kernel não pode
+ * apagar o que já foi preenchido. E o `firebase-functions` valida os `defineString` GLOBALMENTE, não
+ * por function — um parâmetro declarado sem entrada no arquivo recusa o deploy de todas elas, e é por
+ * isso que a lista é escrita a partir do manifesto em vez de copiada de um template.
+ */
+export declare const ensureOfficeEnv: (root: string, projectId: string, parameters: BackendParameter[]) => Promise<EnsureEnvResult>;
+/**
+ * Copia a fonte para onde o `firebase-functions` a lê. Sem isso o valor preenchido na raiz não chega a
+ * function nenhuma, e a falha aparece só quando a feature é usada.
+ */
+export declare const stageOfficeEnv: (root: string, projectId: string, install: string) => Promise<boolean>;
+/**
+ * Garante que o `.env.<projectId>` não vai para um repositório. O diretório é do escritório e tende a
+ * ser versionado — é onde ele guarda as extensões que escreve —, e uma credencial commitada por
+ * omissão nossa é o pior desfecho possível deste comando.
+ *
+ * Cria o arquivo quando não existe. Quando existe, ACRESCENTA só a linha que falta e diz que o fez:
+ * reescrever o `.gitignore` de alguém seria pior que o problema.
+ */
+export declare const ensureRootGitignore: (root: string) => Promise<"created" | "appended" | "ok">;

package/lib/console/backendEnv.js

@@ -0,0 +1,118 @@
+import { access, appendFile, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * As configurações de backend são do ESCRITÓRIO, e por isso moram ao lado do `microteia.yaml` — não
+ * dentro de `.microteia/`.
+ *
+ * Elas moravam lá dentro, e o resultado era perda de dado: o `deploy` substitui o pacote por inteiro
+ * (`rm -rf install` e renomeia o staging), preservando explicitamente só `functions/custom` e
+ * `functions/node_modules`. Uma credencial preenchida à mão em
+ * `.microteia/install/functions/.env.<projectId>` era apagada no deploy seguinte, e o
+ * `ensureBackendEnv` a recriava VAZIA — com o agravante de que a impressão digital deixava de bater, o
+ * provisionamento marcava as functions como obsoletas e as redeployava com a string vazia. Ou seja: o
+ * mecanismo escrito para detectar valor faltando passava a ser a causa dele.
+ *
+ * O diretório do `microteia.yaml` é o repositório de quem mantém a instalação: é onde ficam as
+ * extensões que ele escreve (`extensions/`) e o registro do ambiente. `.microteia/` é descartável por
+ * definição — tudo ali se refaz do tarball mais um `connect` —, e nada que uma pessoa digita pode
+ * depender de sobreviver a isso.
+ *
+ * O arquivo que o `firebase-functions` lê continua tendo de estar em `install/functions/`, então ele é
+ * uma CÓPIA, escrita no deploy. A fonte é a da raiz.
+ */
+/** O arquivo que o escritório edita. O nome leva o projeto: uma instalação, um projeto Firebase. */
+export const officeEnvName = (projectId) => `.env.${projectId}`;
+export const officeEnvPath = (root, projectId) => join(root, officeEnvName(projectId));
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const declaredNames = (content) => new Set(content.split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('#') && line.includes('='))
+    .map((line) => line.slice(0, line.indexOf('=')).trim()));
+/**
+ * Garante que o arquivo existe e declara todo parâmetro do pacote.
+ *
+ * ACRESCENTA o que falta, nunca reescreve: um parâmetro novo numa versão nova do kernel não pode
+ * apagar o que já foi preenchido. E o `firebase-functions` valida os `defineString` GLOBALMENTE, não
+ * por function — um parâmetro declarado sem entrada no arquivo recusa o deploy de todas elas, e é por
+ * isso que a lista é escrita a partir do manifesto em vez de copiada de um template.
+ */
+export const ensureOfficeEnv = async (root, projectId, parameters) => {
+    const path = officeEnvPath(root, projectId);
+    const previous = await exists(path) ? await readFile(path, 'utf8') : null;
+    const declared = declaredNames(previous ?? '');
+    const missing = parameters.filter((parameter) => !declared.has(parameter.name));
+    if (previous !== null && missing.length === 0)
+        return { path, created: false, added: [] };
+    const body = `${missing.map((parameter) => `${parameter.name}=`).join('\n')}\n`;
+    if (previous === null) {
+        const header = `# Backend settings for ${projectId}.\n`
+            + '#\n'
+            + '# Fill in what the features you use need; the rest stays empty. After changing a value, run\n'
+            + '# "microteia provision" — the value is stamped into each Cloud Function at ITS deploy, so a\n'
+            + '# function already running keeps the previous one until it is deployed again.\n'
+            + '#\n'
+            + '# These are credentials. This file is gitignored — keep it that way.\n\n';
+        await writeFile(path, `${header}${body}`);
+        return { path, created: true, added: missing.map((parameter) => parameter.name) };
+    }
+    await appendFile(path, `\n${body}`);
+    return { path, created: false, added: missing.map((parameter) => parameter.name) };
+};
+/**
+ * Copia a fonte para onde o `firebase-functions` a lê. Sem isso o valor preenchido na raiz não chega a
+ * function nenhuma, e a falha aparece só quando a feature é usada.
+ */
+export const stageOfficeEnv = async (root, projectId, install) => {
+    const source = officeEnvPath(root, projectId);
+    // Ausente não é erro: o `provision` pode correr numa instalação que ainda não desempacotou nada, e
+    // quem avisa que falta valor é a conferência de parâmetros, com a lista do que falta.
+    if (!await exists(source))
+        return false;
+    const target = join(install, 'functions', officeEnvName(projectId));
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+    return true;
+};
+const GITIGNORE_LINES = [
+    '# Local Microteia installation: rebuilt from the package plus "microteia connect".',
+    '.microteia/',
+    '',
+    '# Backend settings. These are credentials — never commit them.',
+    '.env.*',
+    '# Ignore examples, which are not part of the installation and are not meant to be committed.',
+    'examples/',
+];
+/** Um padrão que cubra `.env.<projectId>`. Não tenta ser um matcher de gitignore: reconhece os usuais. */
+const coversEnvFiles = (content) => content
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line === '.env.*' || line === '.env*' || line === '*.env' || line === '.env');
+/**
+ * Garante que o `.env.<projectId>` não vai para um repositório. O diretório é do escritório e tende a
+ * ser versionado — é onde ele guarda as extensões que escreve —, e uma credencial commitada por
+ * omissão nossa é o pior desfecho possível deste comando.
+ *
+ * Cria o arquivo quando não existe. Quando existe, ACRESCENTA só a linha que falta e diz que o fez:
+ * reescrever o `.gitignore` de alguém seria pior que o problema.
+ */
+export const ensureRootGitignore = async (root) => {
+    const path = join(root, '.gitignore');
+    if (!await exists(path)) {
+        await writeFile(path, `${GITIGNORE_LINES.join('\n')}\n`);
+        return 'created';
+    }
+    const content = await readFile(path, 'utf8');
+    if (coversEnvFiles(content))
+        return 'ok';
+    const separator = content.endsWith('\n') ? '' : '\n';
+    await appendFile(path, `${separator}\n# Backend settings. These are credentials — never commit them.\n.env.*\n`);
+    return 'appended';
+};

package/lib/console/backendIndexes.d.ts

@@ -0,0 +1,40 @@
+import type { FirestoreIndexSpec } from '../kernel/backendShape.js';
+export declare const encodeIndex: (index: FirestoreIndexSpec) => string;
+export declare const decodeIndex: (entry: string) => FirestoreIndexSpec | null;
+/**
+ * Entrada que não decodifica é DESCARTADA, não fatal. O pior caso de descartar é a memória de um índice
+ * se perder, que é exatamente o comportamento anterior a este módulo; o pior caso de lançar é um
+ * `microteia.yaml` editado à mão impedir um upgrade — e o arquivo fica ao lado das Cloud Functions do
+ * escritório, então ele É editado à mão.
+ */
+export declare const parseIndexState: (raw: string | null) => FirestoreIndexSpec[];
+export interface IndexStateOutcome {
+    value: string | null;
+    skipped: FirestoreIndexSpec[];
+}
+export declare const serializeIndexState: (indexes: FirestoreIndexSpec[]) => IndexStateOutcome;
+/** Uma linha legível, para o relatório — é ela que o operador lê, não o escalar do `microteia.yaml`. */
+export declare const describeIndex: (index: FirestoreIndexSpec) => string;
+export interface IndexesFile {
+    indexes: FirestoreIndexSpec[];
+    fieldOverrides?: unknown[];
+}
+export declare const readIndexFile: (install: string) => Promise<IndexesFile>;
+export declare const writeIndexFile: (install: string, file: IndexesFile) => Promise<void>;
+export interface Convergence {
+    desired: FirestoreIndexSpec[];
+    missing: FirestoreIndexSpec[];
+    changed: boolean;
+}
+/**
+ * `baseline ∪ manter`, na ordem em que chega — reescrever a partir da baseline, e não acrescentar ao que
+ * está lá, é o que faz um índice sair do arquivo quando ele deixa de ser pedido E de ser lembrado.
+ * `missing` é o que o arquivo ainda não declarava, e é ele que decide se vale chamar o `firebase`.
+ */
+export declare const convergeIndexes: (current: FirestoreIndexSpec[], baseline: FirestoreIndexSpec[], keep: FirestoreIndexSpec[]) => Convergence;
+/**
+ * Devolve ao arquivo recém-desempacotado o que a instalação já tinha declarado. É o `unpack` que apaga
+ * `install/`, e é ele que repara — antes de qualquer comando poder rodar `firebase deploy` contra um
+ * arquivo incompleto. Não toca no Firebase: só reescreve o arquivo.
+ */
+export declare const restoreDeclaredIndexes: (install: string, baseline: FirestoreIndexSpec[], recorded: FirestoreIndexSpec[]) => Promise<FirestoreIndexSpec[]>;

package/lib/console/backendIndexes.js

@@ -0,0 +1,178 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { indexKey } from '../kernel/backendShape.js';
+/**
+ * Quais índices compostos de EXTENSÃO já foram declarados neste projeto, guardados na raiz.
+ *
+ * Existe pelo mesmo motivo que `backend.functions`: o estado tem de sobreviver ao `unpack`. O que
+ * havia era só o `firestore.indexes.json` de dentro de `.microteia/install/`, que o `unpack` apaga
+ * inteiro — e o pacote traz apenas a BASELINE, porque o que a extensão reivindica sai dela no `pack`.
+ *
+ * O efeito era este, e chegou a acontecer: provisiona-se (o índice da extensão entra no arquivo e é
+ * criado no projeto), desativa-se a extensão (o índice fica, e é o certo), troca-se de kernel, e o
+ * `microteia deploy` roda `firebase deploy --only firestore:indexes` contra um arquivo que voltou à
+ * baseline. O `firebase` acha no projeto índices que o arquivo não declara e PERGUNTA se pode apagar,
+ * no meio de um upgrade — e responder "sim" leva embora o índice de uma extensão que ainda pode voltar.
+ * Pior: `reportOrphanIndexes` lia a mesma memória apagada, então o aviso que existe para o órfão não
+ * passar em branco emudecia exatamente ali.
+ */
+const ENTRY_SEPARATOR = ';';
+const FIELD_SEPARATOR = ',';
+const SCOPE_SEPARATOR = '/';
+const GROUP_SCOPE = 'group';
+/**
+ * A marca de ordenação é o ÚLTIMO caractere do campo, e não um separador: é o que permite um campo
+ * chamado `order-date` — o `-` no meio não decide nada. `?` é o campo sem ordenação nem `arrayConfig`,
+ * que o Firestore recusa no deploy mas o manifesto de uma extensão pode declarar; representá-lo é mais
+ * barato que uma exceção, e faz a ida e volta ser exata para todo índice que exista.
+ */
+const MARKS = {
+    ASCENDING: '+',
+    DESCENDING: '-',
+    CONTAINS: '*',
+    NONE: '?',
+};
+const encodeField = (field) => {
+    if (field.arrayConfig !== undefined && field.order !== undefined)
+        return null;
+    if (field.arrayConfig !== undefined)
+        return `${field.fieldPath}${MARKS.CONTAINS}`;
+    if (field.order === 'DESCENDING')
+        return `${field.fieldPath}${MARKS.DESCENDING}`;
+    if (field.order === 'ASCENDING')
+        return `${field.fieldPath}${MARKS.ASCENDING}`;
+    return `${field.fieldPath}${MARKS.NONE}`;
+};
+const decodeField = (token) => {
+    const path = token.slice(0, -1);
+    if (path === '')
+        return null;
+    switch (token.slice(-1)) {
+        case MARKS.CONTAINS: return { fieldPath: path, arrayConfig: 'CONTAINS' };
+        case MARKS.DESCENDING: return { fieldPath: path, order: 'DESCENDING' };
+        case MARKS.ASCENDING: return { fieldPath: path, order: 'ASCENDING' };
+        case MARKS.NONE: return { fieldPath: path };
+        default: return null;
+    }
+};
+const MARK_VALUES = Object.values(MARKS);
+/**
+ * O que a codificação não consegue representar sem ambiguidade. Um nome de coleção não pode conter `/`
+ * (o Firestore não permite) e um caminho de campo com `;`, `,` ou `:` só apareceria entre acentos
+ * graves — mas "só apareceria" é como um defeito silencioso começa, então aqui ele é DETECTADO e o
+ * índice fica de fora da memória com aviso, em vez de voltar do arquivo virado noutro índice.
+ */
+const representable = (index) => {
+    const reserved = [ENTRY_SEPARATOR, FIELD_SEPARATOR, ':', SCOPE_SEPARATOR];
+    if (reserved.some((token) => index.collectionGroup.includes(token)))
+        return false;
+    if (index.collectionGroup === '')
+        return false;
+    return index.fields.every((field) => {
+        const encoded = encodeField(field);
+        if (encoded === null)
+            return false;
+        if (reserved.some((token) => field.fieldPath.includes(token)))
+            return false;
+        return !MARK_VALUES.includes(field.fieldPath.slice(-1));
+    });
+};
+export const encodeIndex = (index) => {
+    const scope = index.queryScope === 'COLLECTION_GROUP' ? `${SCOPE_SEPARATOR}${GROUP_SCOPE}` : '';
+    const fields = index.fields.map(encodeField).join(FIELD_SEPARATOR);
+    return `${index.collectionGroup}${scope}:${fields}`;
+};
+export const decodeIndex = (entry) => {
+    const separator = entry.indexOf(':');
+    if (separator <= 0)
+        return null;
+    const head = entry.slice(0, separator);
+    const tail = entry.slice(separator + 1);
+    if (tail === '')
+        return null;
+    const group = head.endsWith(`${SCOPE_SEPARATOR}${GROUP_SCOPE}`);
+    const collectionGroup = group ? head.slice(0, -(GROUP_SCOPE.length + 1)) : head;
+    if (collectionGroup === '' || collectionGroup.includes(SCOPE_SEPARATOR))
+        return null;
+    const fields = tail.split(FIELD_SEPARATOR).map(decodeField);
+    if (fields.some((field) => field === null))
+        return null;
+    return {
+        collectionGroup,
+        queryScope: group ? 'COLLECTION_GROUP' : 'COLLECTION',
+        fields: fields,
+    };
+};
+/**
+ * Entrada que não decodifica é DESCARTADA, não fatal. O pior caso de descartar é a memória de um índice
+ * se perder, que é exatamente o comportamento anterior a este módulo; o pior caso de lançar é um
+ * `microteia.yaml` editado à mão impedir um upgrade — e o arquivo fica ao lado das Cloud Functions do
+ * escritório, então ele É editado à mão.
+ */
+export const parseIndexState = (raw) => {
+    const indexes = new Map();
+    for (const entry of (raw ?? '').split(ENTRY_SEPARATOR)) {
+        const trimmed = entry.trim();
+        if (trimmed === '')
+            continue;
+        const index = decodeIndex(trimmed);
+        if (index !== null)
+            indexes.set(indexKey(index), index);
+    }
+    return [...indexes.values()];
+};
+export const serializeIndexState = (indexes) => {
+    const entries = new Map();
+    const skipped = [];
+    for (const index of indexes) {
+        if (!representable(index)) {
+            skipped.push(index);
+            continue;
+        }
+        entries.set(indexKey(index), encodeIndex(index));
+    }
+    const value = [...entries.values()].sort();
+    return { value: value.length === 0 ? null : value.join(ENTRY_SEPARATOR), skipped };
+};
+/** Uma linha legível, para o relatório — é ela que o operador lê, não o escalar do `microteia.yaml`. */
+export const describeIndex = (index) => {
+    const scope = index.queryScope === 'COLLECTION_GROUP' ? ' (collection group)' : '';
+    return `${index.collectionGroup}${scope}: ${index.fields.map((field) => field.fieldPath).join(', ')}`;
+};
+const indexFilePath = (install) => join(install, 'firestore.indexes.json');
+export const readIndexFile = async (install) => JSON.parse(await readFile(indexFilePath(install), 'utf8'));
+export const writeIndexFile = async (install, file) => {
+    await writeFile(indexFilePath(install), `${JSON.stringify(file, null, 2)}\n`);
+};
+/**
+ * `baseline ∪ manter`, na ordem em que chega — reescrever a partir da baseline, e não acrescentar ao que
+ * está lá, é o que faz um índice sair do arquivo quando ele deixa de ser pedido E de ser lembrado.
+ * `missing` é o que o arquivo ainda não declarava, e é ele que decide se vale chamar o `firebase`.
+ */
+export const convergeIndexes = (current, baseline, keep) => {
+    const desired = [];
+    const present = new Set();
+    for (const index of [...baseline, ...keep]) {
+        const key = indexKey(index);
+        if (present.has(key))
+            continue;
+        present.add(key);
+        desired.push(index);
+    }
+    const declared = new Set(current.map(indexKey));
+    const missing = desired.filter((index) => !declared.has(indexKey(index)));
+    return { desired, missing, changed: missing.length > 0 || current.length !== desired.length };
+};
+/**
+ * Devolve ao arquivo recém-desempacotado o que a instalação já tinha declarado. É o `unpack` que apaga
+ * `install/`, e é ele que repara — antes de qualquer comando poder rodar `firebase deploy` contra um
+ * arquivo incompleto. Não toca no Firebase: só reescreve o arquivo.
+ */
+export const restoreDeclaredIndexes = async (install, baseline, recorded) => {
+    const file = await readIndexFile(install);
+    const convergence = convergeIndexes(file.indexes, baseline, recorded);
+    if (!convergence.changed)
+        return [];
+    await writeIndexFile(install, { ...file, indexes: convergence.desired });
+    return convergence.missing;
+};

package/lib/console/backendParameters.d.ts

@@ -0,0 +1,48 @@
+import type { BackendClaim } from '../kernel/backendShape.js';
+/**
+ * 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 declare const parseBackendEnv: (content: string) => Map<string, string>;
+/**
+ * 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 declare const readBackendEnv: (root: string, projectId: string) => Promise<Map<string, string>>;
+/**
+ * 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 declare const parameterDigest: (projectId: string, name: string, value: string) => string;
+export declare const parameterDigests: (projectId: string, values: Map<string, string>, tracked: string[]) => Map<string, string>;
+/**
+ * `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 declare const parseParameterState: (raw: string | null) => Map<string, string>;
+export declare const serializeParameterState: (state: Map<string, string>) => string | null;
+/**
+ * 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 declare const changedParameters: (recorded: Map<string, string>, current: Map<string, string>, tracked: string[]) => string[];
+/** As functions das extensões que declaram algum destes parâmetros. */
+export declare const functionsDeclaringParameters: (claims: BackendClaim[], names: string[]) => string[];