@microteia/console 2.7.0

package/lib/kernel/backendShape.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A forma de `manifest.backend` redeclarada do lado do Console, pelo mesmo motivo de
+ * `console/runtimeConfigShape.ts`: o Console é publicado sem o `src/` do kernel, então não pode
+ * importar o contrato. `backendShape.test.ts` amarra as duas pontas — separadas em silêncio, o Console
+ * gravaria um fingerprint que o kernel nunca reconhece, e a extensão ficaria pendente para sempre.
+ */
+export interface FirestoreIndexField {
+    fieldPath: string;
+    order?: 'ASCENDING' | 'DESCENDING';
+    arrayConfig?: 'CONTAINS';
+}
+export interface FirestoreIndexSpec {
+    collectionGroup: string;
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
+    fields: FirestoreIndexField[];
+}
+export interface BackendPrerequisite {
+    id: string;
+    title: string;
+    detail: string;
+}
+export interface PluginBackendRequirement {
+    functions?: string[];
+    indexes?: FirestoreIndexSpec[];
+    parameters?: string[];
+    prerequisites?: BackendPrerequisite[];
+}
+/** Uma exigência com o dono dela — é o dono que o relatório nomeia, e o dono que fica pendente. */
+export interface BackendClaim {
+    pluginId: string;
+    name: string;
+    version: string;
+    backend: PluginBackendRequirement;
+}
+/** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
+export declare const backendFingerprint: (backend?: PluginBackendRequirement) => string;
+export declare const hasBackendRequirement: (backend?: PluginBackendRequirement) => boolean;
+/** Chave de identidade de um índice, para deduplicar e para casar reivindicação com a raiz. */
+export declare const indexKey: (index: FirestoreIndexSpec) => string;
+export declare const claimedFunctions: (claims: BackendClaim[]) => string[];
+export declare const claimedIndexes: (claims: BackendClaim[]) => FirestoreIndexSpec[];
+export declare const claimedParameters: (claims: BackendClaim[]) => string[];
+/**
+ * O que o `deploy` sobe sempre: tudo o que foi empacotado menos o que alguma extensão reivindica.
+ * A ordem de `index.ts` é preservada — é a ordem em que o deploy uma-a-uma acontece.
+ */
+export declare const baselineFunctionsOf: (all: string[], claims: BackendClaim[]) => string[];
+export declare const baselineIndexesOf: (rootIndexes: FirestoreIndexSpec[], claims: BackendClaim[]) => FirestoreIndexSpec[];
+/**
+ * Reivindicar function que não foi empacotada, ou a mesma function por duas extensões.
+ *
+ * A primeira deixaria o deploy nomeando uma function inexistente; a segunda tornaria a remoção por
+ * `--prune` indecidível — ninguém sabe de quem é. Vale nos dois lados: no `pack`, contra os templates;
+ * no `provision`, contra o que veio do banco do escritório, que é dado e não código.
+ */
+export declare const functionClaimProblems: (claims: BackendClaim[], packagedFunctions: string[]) => string[];
+/**
+ * Índice reivindicado que não existe na raiz. É conferência de EMPACOTAMENTO, não de provisionamento:
+ * a raiz é o que roda em `microteia-dev` e `curatino`, então uma declaração que não esteja lá deixaria
+ * de criar o índice justamente nos nossos ambientes. Do lado de quem instala a pergunta não faz
+ * sentido — lá o índice reivindicado é, por construção, o que o `pack` tirou da baseline.
+ */
+export declare const indexDeclarationProblems: (claims: BackendClaim[], rootIndexes: FirestoreIndexSpec[]) => string[];
+/** As duas conferências juntas — o que o `pack` exige antes de escrever qualquer coisa. */
+export declare const claimProblems: (claims: BackendClaim[], packagedFunctions: string[], rootIndexes: FirestoreIndexSpec[]) => string[];
+/** As exigências das extensões de primeira parte, lidas dos `extension-templates/*.json` gerados. */
+export declare const claimsFromTemplates: (templates: {
+    manifest?: {
+        id?: string;
+        name?: string;
+        version?: string;
+        backend?: PluginBackendRequirement;
+    };
+}[]) => BackendClaim[];

package/lib/kernel/backendShape.js

@@ -0,0 +1,91 @@
+const canonicalIndex = (index) => JSON.stringify([
+    index.collectionGroup,
+    index.queryScope,
+    index.fields.map((field) => [field.fieldPath, field.order ?? '', field.arrayConfig ?? '']),
+]);
+/** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
+export const backendFingerprint = (backend) => JSON.stringify({
+    functions: [...(backend?.functions ?? [])].sort(),
+    indexes: [...(backend?.indexes ?? [])].map(canonicalIndex).sort(),
+    parameters: [...(backend?.parameters ?? [])].sort(),
+});
+export const hasBackendRequirement = (backend) => (backend?.functions?.length ?? 0) > 0
+    || (backend?.indexes?.length ?? 0) > 0
+    || (backend?.parameters?.length ?? 0) > 0;
+/** Chave de identidade de um índice, para deduplicar e para casar reivindicação com a raiz. */
+export const indexKey = canonicalIndex;
+export const claimedFunctions = (claims) => [...new Set(claims.flatMap((claim) => claim.backend.functions ?? []))].sort();
+export const claimedIndexes = (claims) => {
+    const seen = new Map();
+    for (const claim of claims) {
+        for (const index of claim.backend.indexes ?? [])
+            seen.set(indexKey(index), index);
+    }
+    return [...seen.values()];
+};
+export const claimedParameters = (claims) => [...new Set(claims.flatMap((claim) => claim.backend.parameters ?? []))].sort();
+/**
+ * O que o `deploy` sobe sempre: tudo o que foi empacotado menos o que alguma extensão reivindica.
+ * A ordem de `index.ts` é preservada — é a ordem em que o deploy uma-a-uma acontece.
+ */
+export const baselineFunctionsOf = (all, claims) => {
+    const claimed = new Set(claimedFunctions(claims));
+    return all.filter((name) => !claimed.has(name));
+};
+export const baselineIndexesOf = (rootIndexes, claims) => {
+    const claimed = new Set(claimedIndexes(claims).map(indexKey));
+    return rootIndexes.filter((index) => !claimed.has(indexKey(index)));
+};
+/**
+ * Reivindicar function que não foi empacotada, ou a mesma function por duas extensões.
+ *
+ * A primeira deixaria o deploy nomeando uma function inexistente; a segunda tornaria a remoção por
+ * `--prune` indecidível — ninguém sabe de quem é. Vale nos dois lados: no `pack`, contra os templates;
+ * no `provision`, contra o que veio do banco do escritório, que é dado e não código.
+ */
+export const functionClaimProblems = (claims, packagedFunctions) => {
+    const problems = [];
+    const packaged = new Set(packagedFunctions);
+    const owner = new Map();
+    for (const claim of claims) {
+        for (const name of claim.backend.functions ?? []) {
+            if (!packaged.has(name)) {
+                problems.push(`${claim.pluginId} claims function "${name}", which is not available to deploy`);
+            }
+            const previous = owner.get(name);
+            if (previous !== undefined && previous !== claim.pluginId) {
+                problems.push(`function "${name}" is claimed by both ${previous} and ${claim.pluginId}`);
+            }
+            owner.set(name, claim.pluginId);
+        }
+    }
+    return problems;
+};
+/**
+ * Índice reivindicado que não existe na raiz. É conferência de EMPACOTAMENTO, não de provisionamento:
+ * a raiz é o que roda em `microteia-dev` e `curatino`, então uma declaração que não esteja lá deixaria
+ * de criar o índice justamente nos nossos ambientes. Do lado de quem instala a pergunta não faz
+ * sentido — lá o índice reivindicado é, por construção, o que o `pack` tirou da baseline.
+ */
+export const indexDeclarationProblems = (claims, rootIndexes) => {
+    const rootKeys = new Set(rootIndexes.map(indexKey));
+    return claims.flatMap((claim) => (claim.backend.indexes ?? [])
+        .filter((index) => !rootKeys.has(indexKey(index)))
+        .map((index) => `${claim.pluginId} claims an index on "${index.collectionGroup}" `
+        + `(${index.fields.map((field) => field.fieldPath).join(', ')}) that firestore.indexes.json does not declare`));
+};
+/** As duas conferências juntas — o que o `pack` exige antes de escrever qualquer coisa. */
+export const claimProblems = (claims, packagedFunctions, rootIndexes) => [
+    ...functionClaimProblems(claims, packagedFunctions),
+    ...indexDeclarationProblems(claims, rootIndexes),
+];
+/** As exigências das extensões de primeira parte, lidas dos `extension-templates/*.json` gerados. */
+export const claimsFromTemplates = (templates) => templates
+    .filter((template) => hasBackendRequirement(template.manifest?.backend))
+    .map((template) => ({
+    pluginId: String(template.manifest?.id),
+    name: String(template.manifest?.name ?? template.manifest?.id),
+    version: String(template.manifest?.version ?? '0.0.0'),
+    backend: template.manifest?.backend,
+}))
+    .sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0));

package/lib/kernel/channel.d.ts

@@ -0,0 +1,79 @@
+import type { KernelManifest } from './manifest.js';
+/**
+ * O catálogo de versões publicadas — a forma do `index.json`, e as regras de quem escreve nele e de quem
+ * o lê. Fica em `kernel/` pela mesma razão que o `manifest.ts`: os DOIS lados dependem dele. O `publish`
+ * acrescenta uma entrada, o `unpack` resolve uma versão a partir dela, e uma discordância entre os dois
+ * seria descoberta na máquina de quem instala.
+ *
+ * O índice é o único ponto de acoplamento com onde os arquivos estão hospedados. As URLs são DADO dentro
+ * dele, absolutas, e nada no Console monta uma: trocar de host — ou passar a emitir URL assinada por
+ * escritório — reescreve o índice e não muda comando nenhum que alguém digita. Era o que precisava ser
+ * comprado agora, porque o host escolhido não tem caminho próprio para isso.
+ */
+export declare const INDEX_SCHEMA = 1;
+/**
+ * O canal padrão, e por ora o único. Ele existe como nome — e não como "a maior versão da lista" —
+ * porque publicar não é promover: uma versão pode estar no índice, com URL e hash, sem ser a que uma
+ * instalação recebe ao pedir `latest`.
+ */
+export declare const STABLE_CHANNEL = "stable";
+export declare const LATEST = "latest";
+/**
+ * O nome do arquivo, montado do número e não lido da URL. Quem baixa não deriva nome de caminho que veio
+ * pela rede — e quem empacota usa o mesmo daqui, para que as duas pontas não possam divergir.
+ */
+export declare const kernelTarballName: (version: string) => string;
+export interface ChannelEntry {
+    version: string;
+    kernelVersion: string;
+    minimumCliVersion: string;
+    publishedAt: string;
+    bytes: number;
+    sha256: string;
+    /** URL absoluta do tarball. */
+    tarball: string;
+    /** URL absoluta da cópia externa do manifesto, para ler pré-requisitos sem baixar 7 MB. */
+    manifest: string;
+}
+export interface ChannelIndex {
+    schema: number;
+    channels: Record<string, string>;
+    kernel: ChannelEntry[];
+}
+export declare const emptyIndex: () => ChannelIndex;
+/**
+ * Lê o catálogo RECUSANDO o que não entende, em vez de seguir com campos ausentes.
+ *
+ * O que ele guarda não é a boa formação do JSON: é a impossibilidade de instalar algo cuja integridade
+ * não pode ser conferida. Uma entrada sem `sha256` passaria por uma verificação que não compara nada, e
+ * essa é exatamente a forma de o hash não servir para nada.
+ *
+ * `schema` maior que o desta ferramenta é recusa com o conserto na mão: quem publicou já sabia de algo
+ * que este Console não sabe.
+ */
+export declare const parseIndex: (text: string, source: string) => ChannelIndex;
+export declare const serializeIndex: (index: ChannelIndex) => string;
+/**
+ * A entrada que descreve um pacote, montada do manifesto EXTERNO — o único que carrega o tamanho e o
+ * hash do tarball. Um manifesto sem eles é o de dentro do tarball, ou o de um pacote anterior ao canal,
+ * e nos dois casos publicar seria publicar algo que ninguém consegue verificar.
+ */
+export declare const entryOf: (manifest: KernelManifest, urls: {
+    tarball: string;
+    manifest: string;
+}, publishedAt: string) => ChannelEntry;
+/**
+ * Acrescenta a entrada e promove o canal, RECUSANDO uma versão que já está lá.
+ *
+ * Republicar é a origem de "a mesma versão com dois conteúdos", e ela não tem conserto depois: alguém
+ * conferiu um hash contra o download de ontem e a partir dali as duas instalações discordam sobre o que
+ * `9.8.2` significa. Um número novo custa um minuto.
+ */
+export declare const withEntry: (index: ChannelIndex, entry: ChannelEntry) => ChannelIndex;
+/**
+ * Resolve o que foi pedido — `latest` ou um número — nomeando o que existe quando não acha.
+ *
+ * A recusa lista as versões porque a alternativa é a pessoa tentar de novo com outro palpite. Cinco
+ * bastam: quem pediu uma versão exata e errou quase sempre errou no patch.
+ */
+export declare const resolveVersion: (index: ChannelIndex, requested: string) => ChannelEntry;

package/lib/kernel/channel.js

@@ -0,0 +1,157 @@
+import { compareVersions } from './manifest.js';
+/**
+ * O catálogo de versões publicadas — a forma do `index.json`, e as regras de quem escreve nele e de quem
+ * o lê. Fica em `kernel/` pela mesma razão que o `manifest.ts`: os DOIS lados dependem dele. O `publish`
+ * acrescenta uma entrada, o `unpack` resolve uma versão a partir dela, e uma discordância entre os dois
+ * seria descoberta na máquina de quem instala.
+ *
+ * O índice é o único ponto de acoplamento com onde os arquivos estão hospedados. As URLs são DADO dentro
+ * dele, absolutas, e nada no Console monta uma: trocar de host — ou passar a emitir URL assinada por
+ * escritório — reescreve o índice e não muda comando nenhum que alguém digita. Era o que precisava ser
+ * comprado agora, porque o host escolhido não tem caminho próprio para isso.
+ */
+export const INDEX_SCHEMA = 1;
+/**
+ * O canal padrão, e por ora o único. Ele existe como nome — e não como "a maior versão da lista" —
+ * porque publicar não é promover: uma versão pode estar no índice, com URL e hash, sem ser a que uma
+ * instalação recebe ao pedir `latest`.
+ */
+export const STABLE_CHANNEL = 'stable';
+export const LATEST = 'latest';
+/**
+ * O nome do arquivo, montado do número e não lido da URL. Quem baixa não deriva nome de caminho que veio
+ * pela rede — e quem empacota usa o mesmo daqui, para que as duas pontas não possam divergir.
+ */
+export const kernelTarballName = (version) => `microteia-kernel-${version}.tgz`;
+export const emptyIndex = () => ({
+    schema: INDEX_SCHEMA,
+    channels: {},
+    kernel: [],
+});
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const REQUIRED_TEXT = ['version', 'kernelVersion', 'minimumCliVersion', 'publishedAt', 'tarball', 'manifest'];
+const entryProblems = (value, where) => {
+    if (!isRecord(value))
+        return [`${where} is not an object.`];
+    const problems = REQUIRED_TEXT
+        .filter((field) => typeof value[field] !== 'string' || value[field] === '')
+        .map((field) => `${where} has no ${field}.`);
+    for (const field of ['bytes', 'sha256']) {
+        const actual = value[field];
+        const ok = field === 'bytes' ? typeof actual === 'number' && actual > 0 : typeof actual === 'string';
+        if (!ok)
+            problems.push(`${where} has no ${field}, so what it points at could not be verified.`);
+    }
+    return problems;
+};
+/**
+ * Lê o catálogo RECUSANDO o que não entende, em vez de seguir com campos ausentes.
+ *
+ * O que ele guarda não é a boa formação do JSON: é a impossibilidade de instalar algo cuja integridade
+ * não pode ser conferida. Uma entrada sem `sha256` passaria por uma verificação que não compara nada, e
+ * essa é exatamente a forma de o hash não servir para nada.
+ *
+ * `schema` maior que o desta ferramenta é recusa com o conserto na mão: quem publicou já sabia de algo
+ * que este Console não sabe.
+ */
+export const parseIndex = (text, source) => {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${source} is not valid JSON, so there is no catalog to read.`);
+    }
+    if (!isRecord(value))
+        throw new Error(`${source} does not contain a catalog.`);
+    const schema = value.schema;
+    if (typeof schema !== 'number')
+        throw new Error(`${source} does not say which schema it uses.`);
+    if (schema > INDEX_SCHEMA) {
+        throw new Error(`${source} uses catalog schema ${schema} and this Console understands ${INDEX_SCHEMA}.\n`
+            + 'Update it with "npm i -g @microteia/console".');
+    }
+    const kernel = value.kernel;
+    if (!Array.isArray(kernel))
+        throw new Error(`${source} lists no kernel versions.`);
+    const problems = kernel.flatMap((entry, index) => entryProblems(entry, `${source} entry ${index}`));
+    if (problems.length > 0) {
+        throw new Error(`The catalog cannot be trusted:\n${problems.map((problem) => `  ${problem}`).join('\n')}`);
+    }
+    const channels = isRecord(value.channels) ? value.channels : {};
+    return {
+        schema,
+        channels: Object.fromEntries(Object.entries(channels).filter(([, version]) => typeof version === 'string')),
+        kernel: kernel,
+    };
+};
+export const serializeIndex = (index) => `${JSON.stringify(index, null, 2)}\n`;
+/**
+ * A entrada que descreve um pacote, montada do manifesto EXTERNO — o único que carrega o tamanho e o
+ * hash do tarball. Um manifesto sem eles é o de dentro do tarball, ou o de um pacote anterior ao canal,
+ * e nos dois casos publicar seria publicar algo que ninguém consegue verificar.
+ */
+export const entryOf = (manifest, urls, publishedAt) => {
+    if (manifest.tarball === undefined) {
+        throw new Error('This manifest carries no tarball digest, so the version could not be verified after download.\n'
+            + 'Rebuild the package with "npm run pack:kernel".');
+    }
+    return {
+        version: manifest.version,
+        kernelVersion: manifest.kernelVersion,
+        minimumCliVersion: manifest.minimumCliVersion,
+        publishedAt,
+        bytes: manifest.tarball.bytes,
+        sha256: manifest.tarball.sha256,
+        tarball: urls.tarball,
+        manifest: urls.manifest,
+    };
+};
+const byVersionDescending = (left, right) => compareVersions(right.version, left.version);
+/**
+ * Acrescenta a entrada e promove o canal, RECUSANDO uma versão que já está lá.
+ *
+ * Republicar é a origem de "a mesma versão com dois conteúdos", e ela não tem conserto depois: alguém
+ * conferiu um hash contra o download de ontem e a partir dali as duas instalações discordam sobre o que
+ * `9.8.2` significa. Um número novo custa um minuto.
+ */
+export const withEntry = (index, entry) => {
+    if (index.kernel.some((existing) => existing.version === entry.version)) {
+        throw new Error(`${entry.version} is already published, and a released version is never rewritten.\n`
+            + 'Bump the version in package.json and package it again.');
+    }
+    return {
+        schema: INDEX_SCHEMA,
+        channels: { ...index.channels, [STABLE_CHANNEL]: entry.version },
+        kernel: [entry, ...index.kernel].sort(byVersionDescending),
+    };
+};
+/**
+ * Resolve o que foi pedido — `latest` ou um número — nomeando o que existe quando não acha.
+ *
+ * A recusa lista as versões porque a alternativa é a pessoa tentar de novo com outro palpite. Cinco
+ * bastam: quem pediu uma versão exata e errou quase sempre errou no patch.
+ */
+export const resolveVersion = (index, requested) => {
+    const available = [...index.kernel].sort(byVersionDescending);
+    if (requested === LATEST) {
+        const promoted = index.channels[STABLE_CHANNEL];
+        if (promoted === undefined) {
+            throw new Error('The catalog promotes no version to "latest" yet.');
+        }
+        const entry = available.find((candidate) => candidate.version === promoted);
+        if (entry === undefined) {
+            throw new Error(`The catalog promotes ${promoted} to "latest", and lists no such version.`);
+        }
+        return entry;
+    }
+    const entry = available.find((candidate) => candidate.version === requested);
+    if (entry === undefined) {
+        const names = available.slice(0, 5).map((candidate) => candidate.version);
+        throw new Error(`The catalog has no kernel ${requested}.\n`
+            + (names.length === 0
+                ? 'It lists no versions at all.'
+                : `The most recent are ${names.join(', ')} — or use --version latest.`));
+    }
+    return entry;
+};

package/lib/kernel/manifest.d.ts

@@ -0,0 +1,138 @@
+import type { FirestoreIndexSpec } from './backendShape.js';
+export interface KernelManifestComponent {
+    id: string;
+    path: string;
+}
+export interface KernelPrerequisite {
+    id: string;
+    title: string;
+    detail: string;
+    optional: boolean;
+}
+export interface BackendParameter {
+    name: string;
+    /** Sem `default` no `defineString`, o firebase-functions EXIGE valor e recusa o deploy sem ele. */
+    required: boolean;
+}
+export interface KernelManifest {
+    id: string;
+    name: string;
+    version: string;
+    kernelVersion: string;
+    minimumCliVersion: string;
+    packagedAt: string;
+    components: KernelManifestComponent[];
+    requires: {
+        functionsRegion: string;
+        nodeVersion: string;
+    };
+    /**
+     * TODAS as functions que existem no pacote. Continua sendo a lista completa porque é a fronteira de
+     * validação: uma extensão só pode reivindicar o que foi empacotado.
+     */
+    functions: string[];
+    /**
+     * As que o `deploy` sobe SEMPRE. O que sobra é reivindicado por extensão (`manifest.backend`) e só
+     * sobe quando ela está instalada — empacotar não é deployar.
+     */
+    baselineFunctions: string[];
+    /**
+     * Os índices compostos que o pacote já traz. O que uma extensão reivindica saiu daqui, e é esta
+     * lista que dá ao `provision` a referência exata do que é do kernel — sem ela, distinguir índice do
+     * kernel de índice de extensão desinstalada exigiria adivinhar.
+     */
+    baselineIndexes: FirestoreIndexSpec[];
+    /** Ausente nos pacotes anteriores a 7.51.0, que não conheciam a verificação de alcance. */
+    callables?: string[];
+    backendParameters: BackendParameter[];
+    manualPrerequisites: KernelPrerequisite[];
+    /**
+     * O SDK de autoria que este pacote carrega, quando carrega. Está aqui para que o `plugin-init`
+     * saiba a versão e ache o tarball sem desempacotar nada duas vezes — e para que um pacote
+     * ANTERIOR ao SDK seja reconhecido pela ausência, em vez de gerar um `package.json` apontando
+     * para um arquivo que não existe.
+     */
+    sdk?: KernelSdk;
+    /**
+     * O tamanho e a impressão digital do tarball, presentes SÓ na cópia externa do manifesto — a que fica
+     * ao lado do `.tgz` e é publicada com ele. A cópia de dentro do tarball não pode carregá-los: ela
+     * entra no arquivo cujo hash seria descrito, e nenhum dos dois números existiria ainda.
+     *
+     * É a única diferença entre as duas cópias, e é o que permite ao `unpack` conferir o que baixou.
+     * Ausente nos pacotes anteriores ao canal de distribuição, e ausente também quando o pacote chegou
+     * por caminho de arquivo — ali a conferência não tem contra o que ser feita.
+     */
+    tarball?: KernelTarball;
+}
+export interface KernelTarball {
+    /** O nome do arquivo, não um caminho: onde ele fica é decisão de quem publica. */
+    name: string;
+    bytes: number;
+    sha256: string;
+}
+export interface KernelSdk {
+    version: string;
+    /** O contrato Kernel↔plugins contra o qual o autor escreve. */
+    kernelVersion: string;
+    /** Caminho do tarball dentro do pacote, SEM número de versão — ver `pluginWorkspaceTemplates`. */
+    path: string;
+}
+export declare 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 declare const MINIMUM_CLI_VERSION = "2.1.0";
+export declare 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 declare const GOOGLE_DEFAULT_REGION = "us-central1";
+export declare const REQUIRED_NODE_VERSION = "22";
+export declare const KERNEL_COMPONENTS: KernelManifestComponent[];
+/**
+ * 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 declare const MANUAL_PREREQUISITES: KernelPrerequisite[];
+/**
+ * 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 declare const exportedFunctionNames: (indexSource: string) => string[];
+/**
+ * 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 declare const callableFunctionNames: (source: string) => string[];
+/**
+ * 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 declare const declaredParametersIn: (source: string) => BackendParameter[];
+/** Comparação de versão suficiente para `minimumCliVersion`: três números, sem pré-lançamento. */
+export declare const compareVersions: (left: string, right: string) => number;
+export declare const parseKernelVersion: (source: string) => string;