@microteia/console 2.7.0

package/lib/console/firestoreRest.js

@@ -0,0 +1,131 @@
+import { captureOrThrow } from '../shared/run.js';
+/**
+ * Leitura e escrita de documento pela REST do Firestore.
+ *
+ * Por que existe: o `provision` precisa saber o que o escritório INSTALOU, e isso só está no banco do
+ * escritório. O `firebase` não tem comando para ler nem gravar um documento, então o caminho é a API
+ * com o token de quem está na máquina.
+ *
+ * O Console continua sem autenticação própria e sem ver credencial: o token vem do `gcloud`, que já é
+ * requisito de quem instala (é ele que cria o App Engine). Nada é guardado — o token é pedido a cada
+ * execução e vive só na memória do processo.
+ */
+const HOST = 'https://firestore.googleapis.com/v1';
+const GCLOUD_BIN = 'gcloud';
+let cachedToken = null;
+export const accessToken = async () => {
+    if (cachedToken !== null)
+        return cachedToken;
+    try {
+        cachedToken = (await captureOrThrow(GCLOUD_BIN, ['auth', 'print-access-token'])).trim();
+    }
+    catch {
+        throw new Error('Could not get a Google access token. Sign in once with: gcloud auth login\n'
+            + '  (the Console never stores credentials — it asks gcloud every time)');
+    }
+    if (cachedToken === '')
+        throw new Error('gcloud returned an empty access token. Run: gcloud auth login');
+    return cachedToken;
+};
+/**
+ * `X-Goog-User-Project` diz de qual projeto é a cota. Sem ele, uma credencial de usuário é recusada
+ * com uma mensagem sobre "quota project" que não menciona o que fazer.
+ */
+const request = async (projectId, path, init = { method: 'GET' }) => {
+    const token = await accessToken();
+    const url = new URL(`${HOST}/projects/${projectId}/databases/(default)/documents${path}`);
+    for (const [key, value] of Object.entries(init.query ?? {})) {
+        for (const item of Array.isArray(value) ? value : [value])
+            url.searchParams.append(key, item);
+    }
+    const response = await fetch(url, {
+        method: init.method,
+        headers: {
+            authorization: `Bearer ${token}`,
+            'x-goog-user-project': projectId,
+            ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+        },
+        ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        const detail = text.slice(0, 400);
+        if (response.status === 403) {
+            throw new Error(`Firestore refused the request for ${projectId} (403). The signed-in gcloud account needs `
+                + `access to the project's database.\n  ${detail}`);
+        }
+        throw new Error(`Firestore answered ${response.status} for ${path}.\n  ${detail}`);
+    }
+    return text === '' ? {} : JSON.parse(text);
+};
+/** Um valor tipado da REST virando valor de JavaScript. Timestamp vira string ISO, que é o que basta. */
+export const decodeValue = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const typed = value;
+    if ('stringValue' in typed)
+        return typed.stringValue;
+    if ('booleanValue' in typed)
+        return typed.booleanValue;
+    if ('integerValue' in typed)
+        return Number(typed.integerValue);
+    if ('doubleValue' in typed)
+        return typed.doubleValue;
+    if ('timestampValue' in typed)
+        return typed.timestampValue;
+    if ('nullValue' in typed)
+        return null;
+    if ('arrayValue' in typed) {
+        const values = typed.arrayValue?.values ?? [];
+        return values.map(decodeValue);
+    }
+    if ('mapValue' in typed)
+        return decodeFields(typed.mapValue?.fields ?? {});
+    return undefined;
+};
+export const decodeFields = (fields) => Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, decodeValue(value)]));
+/**
+ * Os documentos de uma coleção, seguindo a paginação até o fim.
+ *
+ * Sem máscara de campo, e de propósito: mascarar um caminho aninhado (`package.manifest`) funciona até
+ * uma versão da API discordar da forma, e o sintoma seria uma extensão sumindo do provisionamento sem
+ * erro. Documento de extensão é grande, mas são poucos por escritório, e isto roda uma vez por comando.
+ */
+export const listDocuments = async (projectId, path) => {
+    const documents = [];
+    let pageToken;
+    do {
+        const page = await request(projectId, path, {
+            method: 'GET',
+            query: { pageSize: '300', ...(pageToken === undefined ? {} : { pageToken }) },
+        });
+        for (const entry of page.documents ?? []) {
+            documents.push({ name: entry.name, fields: entry.fields ?? {} });
+        }
+        pageToken = page.nextPageToken;
+    } while (pageToken !== undefined);
+    return documents;
+};
+export const documentId = (document) => document.name.slice(document.name.lastIndexOf('/') + 1);
+export const asString = (value) => ({ stringValue: value });
+/**
+ * Data como DATA, e não como texto que se parece com uma.
+ *
+ * O tipo do valor gravado é escolhido aqui e lido do outro lado do produto, meses depois, por quem não
+ * viu esta linha. Gravar uma data como `stringValue` custou um botão que não funcionava: a tela lia o
+ * texto, exibia certo, e só falhava ao gravar de volta. O `timestampValue` fecha essa porta — e é
+ * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
+ * exatamente o que `toISOString` devolve.
+ */
+export const asTimestamp = (value) => ({ timestampValue: value.toISOString() });
+/**
+ * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o
+ * Console carimbar o estado sem conhecer (nem arriscar reescrever) o pacote inteiro que vive ao lado.
+ */
+export const patchMapField = async (projectId, path, field, entries) => {
+    await request(projectId, path, {
+        method: 'PATCH',
+        query: { 'updateMask.fieldPaths': field },
+        body: { fields: { [field]: { mapValue: { fields: entries } } } },
+    });
+};

package/lib/console/hostingCheck.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Publicar não é o mesmo que SERVIR.
+ *
+ * O `index.html` de um SPA aponta para um bundle com hash no nome, e o Firebase o serve com
+ * `max-age=3600` quando a configuração não diz nada — então, por uma hora depois de um deploy, um
+ * navegador que já esteve no site recebe o HTML ANTIGO, que aponta para o bundle antigo, que está
+ * cacheado como `immutable`. O resultado é a aplicação continuar rodando a versão anterior, com o
+ * deploy tendo terminado em sucesso: o rodapé mostra uma versão que não é a instalada, e não há nada
+ * na saída do deploy que explique isso.
+ *
+ * A verificação compara o bundle que o pacote instalou com o que a URL de verdade devolve, pelo mesmo
+ * caminho do navegador. É a irmã de `callableAccess`: uma confere se o servidor responde, esta confere
+ * se o cliente recebe.
+ */
+export type HostingServed = 'current' | 'stale' | 'unknown';
+export interface HostingCheck {
+    served: HostingServed;
+    packagedBundle: string | null;
+    servedBundle: string | null;
+    /** `Cache-Control` do HTML. Um `max-age` longo aqui é o que faz um deploy demorar a aparecer. */
+    htmlCacheControl: string | null;
+}
+export declare const bundleReferenceIn: (html: string) => string | null;
+/**
+ * Um `max-age` maior que zero no HTML é o bastante para atrasar a versão nova. `no-cache` e
+ * `no-store` são as duas formas de dizer "revalide sempre", e qualquer uma delas está correta.
+ */
+export declare const htmlIsRevalidated: (cacheControl: string | null) => boolean;
+export declare const checkHostingServed: (install: string, origin: string) => Promise<HostingCheck>;

package/lib/console/hostingCheck.js

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const BUNDLE_PATTERN = /assets\/index-[A-Za-z0-9_-]+\.js/;
+export const bundleReferenceIn = (html) => html.match(BUNDLE_PATTERN)?.[0] ?? null;
+/**
+ * Um `max-age` maior que zero no HTML é o bastante para atrasar a versão nova. `no-cache` e
+ * `no-store` são as duas formas de dizer "revalide sempre", e qualquer uma delas está correta.
+ */
+export const htmlIsRevalidated = (cacheControl) => {
+    if (cacheControl === null)
+        return false;
+    const value = cacheControl.toLowerCase();
+    if (value.includes('no-cache') || value.includes('no-store'))
+        return true;
+    const maxAge = value.match(/max-age=(\d+)/);
+    return maxAge !== null && Number.parseInt(maxAge[1], 10) === 0;
+};
+export const checkHostingServed = async (install, origin) => {
+    const packagedBundle = await readFile(join(install, 'hosting', 'index.html'), 'utf8')
+        .then(bundleReferenceIn)
+        .catch(() => null);
+    try {
+        const response = await fetch(`${origin}/index.html`, {
+            // O objetivo é ver o que a origem serve, então nada de cache intermediário nosso.
+            headers: { 'cache-control': 'no-cache' },
+            signal: AbortSignal.timeout(10_000),
+        });
+        const html = await response.text();
+        const servedBundle = bundleReferenceIn(html);
+        const htmlCacheControl = response.headers.get('cache-control');
+        return {
+            served: servedBundle === null || packagedBundle === null
+                ? 'unknown'
+                : servedBundle === packagedBundle ? 'current' : 'stale',
+            packagedBundle,
+            servedBundle,
+            htmlCacheControl,
+        };
+    }
+    catch {
+        // Rede indisponível ou proxy no caminho: avisa sem acusar, como a verificação das callables.
+        return { served: 'unknown', packagedBundle, servedBundle: null, htmlCacheControl: null };
+    }
+};

package/lib/console/init.d.ts

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

package/lib/console/init.js

@@ -0,0 +1,60 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { flagValue, hasFlag } from '../shared/args.js';
+import { blank, bullets, heading, info, success } from '../shared/ui.js';
+import { DEFAULT_FUNCTIONS_REGION } from '../kernel/manifest.js';
+import { ENVIRONMENT_FILE, slug, writeEnvironment } from './environment.js';
+import { WORKSPACE_DIR } from './workspace.js';
+import { ensureRootGitignore } from './backendEnv.js';
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const init = async (args) => {
+    const file = resolve(flagValue(args, 'file') ?? join(process.cwd(), ENVIRONMENT_FILE));
+    const directory = dirname(file);
+    if (await exists(file) && !hasFlag(args, 'force')) {
+        throw new Error(`${file} already exists. Use --force to overwrite it.`);
+    }
+    const name = flagValue(args, 'name') ?? basename(directory);
+    const id = flagValue(args, 'id') ?? slug(name);
+    if (id === '')
+        throw new Error('Could not derive an environment id. Pass --id explicitly.');
+    const environment = {
+        project: { name },
+        environment: { id, name },
+        firebase: { projectId: null, region: DEFAULT_FUNCTIONS_REGION },
+        kernel: { version: null, deployed: null },
+        backend: { functions: null, parameters: null, indexes: null },
+    };
+    await writeEnvironment(file, environment);
+    // O diretório de trabalho guarda o pacote desempacotado e a configuração resolvida. Ele é local à
+    // instalação e não deve ir para repositório nenhum.
+    const workspace = join(directory, WORKSPACE_DIR);
+    await mkdir(workspace, { recursive: true });
+    await writeFile(join(workspace, '.gitignore'), '*\n');
+    // Este diretório é o REPOSITÓRIO de quem mantém a instalação: é onde ficam o registro do ambiente,
+    // as extensões que ele escreve e as configurações de backend. O `.gitignore` nasce com ele porque a
+    // configuração de backend é credencial, e uma credencial commitada por omissão nossa é o pior
+    // desfecho possível.
+    const gitignore = await ensureRootGitignore(directory);
+    heading(`Microteia installation "${name}"`);
+    success(`created ${ENVIRONMENT_FILE}`);
+    if (gitignore === 'created')
+        success('created .gitignore');
+    else if (gitignore === 'appended')
+        success('added ".env.*" to .gitignore');
+    blank();
+    info('Next:');
+    bullets([
+        'microteia connect --project <your-firebase-project-id>',
+        'microteia unpack --version latest',
+        'microteia deploy',
+    ]);
+    blank();
+};

package/lib/console/pluginWorkspace.d.ts

@@ -0,0 +1,48 @@
+import type { ParsedArgs } from '../shared/args.js';
+/**
+ * `microteia plugin-init` — prepara `extensions/`, onde o escritório escreve extensão em TypeScript.
+ *
+ * Não é um deploy e não toca no projeto Firebase: escreve uma semente, chama o `npm` e delega o resto
+ * ao SDK. É deliberadamente o mesmo desenho de `functions/custom/`: o diretório fica FORA de
+ * `.microteia/`, é do escritório, e o upgrade não o toca.
+ *
+ * O que este comando NÃO faz mais é escrever documentação. `AGENTS.md`, `AUTHORING.md`, `tsconfig.json`
+ * e `.mcp.json` descrevem o que o kernel sabe fazer, e por isso saem do SDK — que viaja no mesmo pacote
+ * que aquelas capacidades. Enquanto saíam daqui, ficavam parados na versão do Console que rodou uma vez,
+ * meses antes, e ninguém tinha como notar.
+ */
+export declare const EXTENSIONS_DIR = "extensions";
+/**
+ * Traz o SDK do pacote instalado e manda ELE reescrever o que é gerado no diretório.
+ *
+ * Os três passos são um só movimento, e a ordem é o que faz cada um valer:
+ *
+ * 1. `npm install <tarball>` pelo CAMINHO. Um `npm install` puro diria "up to date": o caminho não leva
+ *    versão e o lock guarda a impressão digital do anterior — era assim que um escritório passava meses
+ *    compilando contra um contrato que a instalação já não tinha.
+ * 2. `microteia-plugin sync`, do SDK que acabou de chegar. É ele que sabe o que o kernel faz.
+ * 3. `npm install`, porque o passo 2 pode ter acrescentado uma devDependency que o kernel novo exige.
+ *
+ * Duas decisões do passo 1 vêm de teste, não de leitura, e sem elas o movimento se desfaz sozinho:
+ *
+ * - **Sem `--no-save`.** Com ele o pacote NOVO é extraído e o `package-lock.json` fica no anterior — e
+ *   aí o passo 3 reinstala o antigo, silenciosamente, desfazendo o passo 1. Pior: mesmo sem o passo 3,
+ *   o próximo `npm install` que alguém rodasse faria a mesma reversão. Salvar é o que casa lock e
+ *   `node_modules`.
+ * - **Caminho RELATIVO ao diretório.** O `npm` reescreve a dependência com o caminho que recebeu; um
+ *   absoluto entraria no `package.json`, e o motivo de ele ser relativo é a instalação poder ser movida
+ *   ou versionada. Sendo relativo, a linha sai idêntica à que já estava lá.
+ *
+ * Usado pelo `plugin-init` e pelo `unpack` — o mesmo caminho, para que não exista um "init" que faz uma
+ * coisa e um "upgrade" que faz outra.
+ */
+export declare const syncAuthoringWorkspace: (directory: string, sdkPath: string, installDir: string, officeName: string) => Promise<void>;
+/**
+ * Depois de trocar de kernel, põe `extensions/` em dia — se ele existir. Chamado pelo `unpack`.
+ *
+ * A falha aqui NÃO derruba o comando. Trocar de kernel é a operação principal, e um `npm` sem rede não
+ * pode impedi-la: o pior resultado possível é uma instalação pela metade porque a documentação de um
+ * diretório opcional não pôde ser reescrita. O aviso diz o comando que resolve.
+ */
+export declare const refreshAuthoringWorkspace: (root: string, officeName: string) => Promise<boolean>;
+export declare const pluginInit: (args: ParsedArgs) => Promise<void>;

package/lib/console/pluginWorkspace.js

@@ -0,0 +1,148 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { flagValue, hasFlag } from '../shared/args.js';
+import { blank, bullets, heading, info, success, warn } from '../shared/ui.js';
+import { run } from '../shared/run.js';
+import { ENVIRONMENT_FILE, readEnvironment } from './environment.js';
+import { WORKSPACE_DIR } from './workspace.js';
+import { SDK_TARBALL, workspacePackageJson } from '../vendor/pluginWorkspaceTemplates.js';
+/**
+ * `microteia plugin-init` — prepara `extensions/`, onde o escritório escreve extensão em TypeScript.
+ *
+ * Não é um deploy e não toca no projeto Firebase: escreve uma semente, chama o `npm` e delega o resto
+ * ao SDK. É deliberadamente o mesmo desenho de `functions/custom/`: o diretório fica FORA de
+ * `.microteia/`, é do escritório, e o upgrade não o toca.
+ *
+ * O que este comando NÃO faz mais é escrever documentação. `AGENTS.md`, `AUTHORING.md`, `tsconfig.json`
+ * e `.mcp.json` descrevem o que o kernel sabe fazer, e por isso saem do SDK — que viaja no mesmo pacote
+ * que aquelas capacidades. Enquanto saíam daqui, ficavam parados na versão do Console que rodou uma vez,
+ * meses antes, e ninguém tinha como notar.
+ */
+export const EXTENSIONS_DIR = 'extensions';
+/** O binário do SDK, dentro do próprio workspace. Ver `workspaceMcpJson` para o porquê de não ser `npx`. */
+const SDK_CLI = 'node_modules/@microteia/sdk/lib/sdk/node/cli.js';
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Acha o SDK no pacote desempacotado. O manifesto o declara desde a versão que passou a carregá-lo; um
+ * pacote anterior a ela não tem SDK, e dizer isso é melhor que escrever um `package.json` apontando
+ * para um caminho que não existe.
+ */
+const locateSdk = async (root) => {
+    const installDir = join(root, WORKSPACE_DIR, 'install');
+    const manifestPath = join(installDir, 'manifest.json');
+    if (!await exists(manifestPath)) {
+        throw new Error('No installed Microteia package found. Run "microteia unpack --version latest" first.');
+    }
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    const sdkDir = join(installDir, 'sdk');
+    if (manifest.sdk === undefined || !await exists(join(sdkDir, SDK_TARBALL))) {
+        throw new Error(`The installed package (${manifest.version}) does not carry the authoring SDK.\n`
+            + 'Install a newer Microteia package, then run this again.');
+    }
+    return {
+        version: manifest.sdk.version,
+        kernelVersion: manifest.sdk.kernelVersion,
+        path: join(sdkDir, SDK_TARBALL),
+    };
+};
+/**
+ * Traz o SDK do pacote instalado e manda ELE reescrever o que é gerado no diretório.
+ *
+ * Os três passos são um só movimento, e a ordem é o que faz cada um valer:
+ *
+ * 1. `npm install <tarball>` pelo CAMINHO. Um `npm install` puro diria "up to date": o caminho não leva
+ *    versão e o lock guarda a impressão digital do anterior — era assim que um escritório passava meses
+ *    compilando contra um contrato que a instalação já não tinha.
+ * 2. `microteia-plugin sync`, do SDK que acabou de chegar. É ele que sabe o que o kernel faz.
+ * 3. `npm install`, porque o passo 2 pode ter acrescentado uma devDependency que o kernel novo exige.
+ *
+ * Duas decisões do passo 1 vêm de teste, não de leitura, e sem elas o movimento se desfaz sozinho:
+ *
+ * - **Sem `--no-save`.** Com ele o pacote NOVO é extraído e o `package-lock.json` fica no anterior — e
+ *   aí o passo 3 reinstala o antigo, silenciosamente, desfazendo o passo 1. Pior: mesmo sem o passo 3,
+ *   o próximo `npm install` que alguém rodasse faria a mesma reversão. Salvar é o que casa lock e
+ *   `node_modules`.
+ * - **Caminho RELATIVO ao diretório.** O `npm` reescreve a dependência com o caminho que recebeu; um
+ *   absoluto entraria no `package.json`, e o motivo de ele ser relativo é a instalação poder ser movida
+ *   ou versionada. Sendo relativo, a linha sai idêntica à que já estava lá.
+ *
+ * Usado pelo `plugin-init` e pelo `unpack` — o mesmo caminho, para que não exista um "init" que faz uma
+ * coisa e um "upgrade" que faz outra.
+ */
+export const syncAuthoringWorkspace = async (directory, sdkPath, installDir, officeName) => {
+    const tarball = relative(directory, sdkPath);
+    await run('npm', ['install', '--no-audit', '--no-fund', tarball], { cwd: directory });
+    await run('node', [SDK_CLI, 'sync', '--install', installDir, '--office', officeName], { cwd: directory });
+    await run('npm', ['install', '--no-audit', '--no-fund'], { cwd: directory });
+};
+/**
+ * Depois de trocar de kernel, põe `extensions/` em dia — se ele existir. Chamado pelo `unpack`.
+ *
+ * A falha aqui NÃO derruba o comando. Trocar de kernel é a operação principal, e um `npm` sem rede não
+ * pode impedi-la: o pior resultado possível é uma instalação pela metade porque a documentação de um
+ * diretório opcional não pôde ser reescrita. O aviso diz o comando que resolve.
+ */
+export const refreshAuthoringWorkspace = async (root, officeName) => {
+    const directory = join(root, EXTENSIONS_DIR);
+    if (!await exists(join(directory, 'package.json')))
+        return false;
+    const installDir = join(root, WORKSPACE_DIR, 'install');
+    try {
+        const sdk = await locateSdk(root);
+        await syncAuthoringWorkspace(directory, sdk.path, installDir, officeName);
+        success(`${EXTENSIONS_DIR}/ is on the new contract (${sdk.kernelVersion})`);
+        return true;
+    }
+    catch (error) {
+        warn(`could not update ${EXTENSIONS_DIR}/: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        info(`  run "npm run sdk:refresh" in ${EXTENSIONS_DIR}/ — until then its guides describe the previous contract.`);
+        return false;
+    }
+};
+export const pluginInit = async (args) => {
+    const file = resolve(flagValue(args, 'file') ?? join(process.cwd(), ENVIRONMENT_FILE));
+    const root = dirname(file);
+    const environment = await readEnvironment(file);
+    const directory = resolve(flagValue(args, 'dir') ?? join(root, EXTENSIONS_DIR));
+    const force = hasFlag(args, 'force');
+    if (await exists(join(directory, 'package.json')) && !force) {
+        throw new Error(`${relative(root, directory)}/package.json already exists.\n`
+            + 'Nothing to do: "microteia unpack" keeps its generated files up to date, and "npm run sync"\n'
+            + 'in that directory does it by hand. Use --force only to rewrite the seed itself.');
+    }
+    const sdk = await locateSdk(root);
+    const installDir = join(root, WORKSPACE_DIR, 'install');
+    heading(`Extension authoring for "${environment.project.name}"`);
+    await mkdir(directory, { recursive: true });
+    // O caminho do tarball é relativo, para que o diretório continue válido se a instalação inteira for
+    // movida — o que acontece assim que alguém a versiona num repositório do escritório.
+    await writeFile(join(directory, 'package.json'), workspacePackageJson(environment.environment.id, relative(directory, sdk.path)));
+    success('wrote the seed package.json');
+    blank();
+    info('Installing @microteia/sdk and writing the guides...');
+    await syncAuthoringWorkspace(directory, sdk.path, installDir, environment.project.name);
+    blank();
+    info(`Extension authoring ready in ${relative(root, directory)}/ (kernel contract ${sdk.kernelVersion}).`);
+    bullets([
+        `cd ${relative(process.cwd(), directory) || '.'}`,
+        'npm run create',
+        'npx tsc --noEmit && npm run check -- hello/plugin.ts',
+        'npm run build -- hello/plugin.ts',
+    ]);
+    blank();
+    info('Read AUTHORING.md first. An AI assistant in this directory reads AGENTS.md and CLAUDE.md, and');
+    info('can query this installation through the MCP server registered in .mcp.json.');
+    blank();
+    info('CLAUDE.md and README.md are yours — nothing rewrites them. Everything else in there is');
+    info('generated, and "microteia unpack" rewrites it whenever this installation takes a new version,');
+    info('so the guides never describe a contract the platform no longer has.');
+    blank();
+};

package/lib/console/provision.d.ts

@@ -0,0 +1,70 @@
+import type { ParsedArgs } from '../shared/args.js';
+import type { KernelManifest } from '../kernel/manifest.js';
+import type { BackendClaim } from '../kernel/backendShape.js';
+import type { Environment } from './environment.js';
+/** Uma exigência, o escritório que a instalou e o documento que carrega o estado dela. */
+export interface InstalledClaim extends BackendClaim {
+    tenantId: string;
+    documentPath: string;
+    applied: boolean;
+}
+/**
+ * O que cada escritório do projeto instalou e exige do backend.
+ *
+ * A exigência vem do banco, então ela é DADO e não código — é por isso que `claimProblems` a confere
+ * contra `manifest.functions` antes de qualquer deploy. Nome de function fora do pacote é recusado com
+ * explicação; não há injeção possível, porque o código é sempre o do pacote.
+ */
+export declare const readInstalledClaims: (projectId: string) => Promise<InstalledClaim[]>;
+export declare const parseAppliedFunctions: (value: string | null) => string[];
+export interface ProvisionOptions {
+    projectId: string;
+    region: string;
+    install: string;
+    manifest: KernelManifest;
+    delaySeconds: number;
+    prune: boolean;
+    environmentFile: string;
+    environment: Environment;
+}
+export interface ProvisionOutcome {
+    deployed: string[];
+    failed: string[];
+    orphans: string[];
+    pending: InstalledClaim[];
+}
+/**
+ * O motor: alinha o projeto Firebase com o que as extensões instaladas exigem, e carimba nelas o
+ * estado. Um motor só, chamado pelo `deploy` no fim e pelo `provision` sozinho — duas implementações
+ * divergiriam exatamente no ponto em que ninguém olha.
+ */
+export declare const provisionBackend: (options: ProvisionOptions) => Promise<ProvisionOutcome>;
+/**
+ * A lista aplicada CONVERGE para o que ainda é exigido: o que já estava e continua sendo pedido, mais
+ * o que subiu agora, mais o órfão que não foi removido. Reescrevê-la só com o que subiu NESTA execução
+ * a esvaziava na segunda passada — e a terceira redeployava tudo, achando que nada havia sido feito.
+ */
+export declare const appliedAfterRun: (input: {
+    alreadyApplied: string[];
+    wanted: string[];
+    deployed: string[];
+    keptOrphans: string[];
+}) => string[];
+/**
+ * A impressão digital do parâmetro só avança quando TODAS as functions que o carregam subiram. Gravar
+ * antes disso é o que transformaria uma falha de deploy em silêncio permanente: o valor novo ficaria
+ * registrado como aplicado, e nenhuma execução seguinte tentaria de novo.
+ *
+ * O que não é mais reivindicado por extensão nenhuma fica registrado em vez de ser removido: apagar
+ * faria uma extensão reinstalada redeployar functions que já carregam o valor certo, e uma linha a mais
+ * no arquivo não decide nada.
+ */
+export declare const appliedParameterState: (input: {
+    recorded: Map<string, string>;
+    current: Map<string, string>;
+    changed: string[];
+    failed: string[];
+    claims: BackendClaim[];
+}) => Map<string, string>;
+/** O comando: provisiona sem reenviar o kernel. É o que se roda depois de instalar uma extensão. */
+export declare const provision: (args: ParsedArgs) => Promise<void>;