@microteia/console 2.10.0 → 2.19.0

package/lib/kernel/backendShape.d.ts

@@ -54,6 +54,33 @@ export declare const baselineIndexesOf: (rootIndexes: FirestoreIndexSpec[], clai
  * 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[];
+/**
+ * Reivindicar uma function que a PLATAFORMA sobe sempre.
+ *
+ * É conferência de PROVISIONAMENTO, não de empacotamento, e a assimetria é da própria definição: no
+ * `pack` a baseline é DERIVADA (`todas − reivindicadas`), então reivindicar é o que tira o nome dela e
+ * a pergunta não existe. Do lado de quem instala a baseline já está decidida e viaja no manifesto, e
+ * aí a reivindicação de um nome dela é uma contradição com duas consequências, nenhuma visível: o
+ * `deploy` sobe a function de qualquer jeito, e a desinstalação da extensão faz `--prune` apagar um
+ * gatilho do produto num escritório que não fez nada.
+ */
+export declare const baselineClaimProblems: (claims: BackendClaim[], baselineFunctions: string[]) => string[];
+/**
+ * Reivindicar uma function COMUM do escritório — a que mora em `functions/`, ao lado do
+ * `microteia.yaml`.
+ *
+ * É o mesmo defeito de reivindicar uma function da plataforma, com o mesmo par de consequências
+ * invisíveis, e por isso é conferido no mesmo lugar. A comum não tem dono por construção: ela é o lugar
+ * de quem serve várias extensões, nenhuma pode declará-la (duas reivindicando o mesmo nome é recusa), e
+ * o `deploy` a sobe SEMPRE. Reivindicá-la, então, não muda nada enquanto a extensão está instalada — e
+ * no dia em que ela sai, a function vira órfã, `--prune` a apaga, e o `deploy` seguinte a repõe. As
+ * outras extensões que dependiam dela perdem o backend numa janela que nada explica, e a fonte continua
+ * intacta em `functions/`, sem nada na árvore que sequer sugira o que aconteceu.
+ *
+ * A assimetria com o `pack` é a mesma de `baselineClaimProblems`: o pacote do kernel não sabe o que o
+ * escritório vai escrever em `functions/`, então a pergunta só existe do lado de quem instala.
+ */
+export declare const sharedClaimProblems: (claims: BackendClaim[], sharedFunctions: 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

package/lib/kernel/backendShape.js

@@ -61,6 +61,44 @@ export const functionClaimProblems = (claims, packagedFunctions) => {
     }
     return problems;
 };
+/**
+ * Reivindicar uma function que a PLATAFORMA sobe sempre.
+ *
+ * É conferência de PROVISIONAMENTO, não de empacotamento, e a assimetria é da própria definição: no
+ * `pack` a baseline é DERIVADA (`todas − reivindicadas`), então reivindicar é o que tira o nome dela e
+ * a pergunta não existe. Do lado de quem instala a baseline já está decidida e viaja no manifesto, e
+ * aí a reivindicação de um nome dela é uma contradição com duas consequências, nenhuma visível: o
+ * `deploy` sobe a function de qualquer jeito, e a desinstalação da extensão faz `--prune` apagar um
+ * gatilho do produto num escritório que não fez nada.
+ */
+export const baselineClaimProblems = (claims, baselineFunctions) => {
+    const baseline = new Set(baselineFunctions);
+    return claims.flatMap((claim) => (claim.backend.functions ?? [])
+        .filter((name) => baseline.has(name))
+        .map((name) => `${claim.pluginId} claims function "${name}", which the platform itself deploys`));
+};
+/**
+ * Reivindicar uma function COMUM do escritório — a que mora em `functions/`, ao lado do
+ * `microteia.yaml`.
+ *
+ * É o mesmo defeito de reivindicar uma function da plataforma, com o mesmo par de consequências
+ * invisíveis, e por isso é conferido no mesmo lugar. A comum não tem dono por construção: ela é o lugar
+ * de quem serve várias extensões, nenhuma pode declará-la (duas reivindicando o mesmo nome é recusa), e
+ * o `deploy` a sobe SEMPRE. Reivindicá-la, então, não muda nada enquanto a extensão está instalada — e
+ * no dia em que ela sai, a function vira órfã, `--prune` a apaga, e o `deploy` seguinte a repõe. As
+ * outras extensões que dependiam dela perdem o backend numa janela que nada explica, e a fonte continua
+ * intacta em `functions/`, sem nada na árvore que sequer sugira o que aconteceu.
+ *
+ * A assimetria com o `pack` é a mesma de `baselineClaimProblems`: o pacote do kernel não sabe o que o
+ * escritório vai escrever em `functions/`, então a pergunta só existe do lado de quem instala.
+ */
+export const sharedClaimProblems = (claims, sharedFunctions) => {
+    const shared = new Set(sharedFunctions);
+    return claims.flatMap((claim) => (claim.backend.functions ?? [])
+        .filter((name) => shared.has(name))
+        .map((name) => `${claim.pluginId} claims function "${name}", which is a shared function of this `
+        + 'installation'));
+};
 /**
  * Í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

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * 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.10.0";
+export declare const CLI_VERSION = "2.19.0";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * 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.10.0';
+export const CLI_VERSION = '2.19.0';

package/lib/vendor/packageTemplates.d.ts

@@ -16,10 +16,21 @@ export interface HostingConfig {
     headers: unknown[];
 }
 export declare const packageFirebaseJson: (hosting: HostingConfig) => string;
+/**
+ * O nome do pacote de functions da instalação, e o subcaminho da superfície curada que a Cloud Function
+ * do ESCRITÓRIO importa dele: `import { forInstalledExtension } from 'microteia-functions/office'`.
+ *
+ * O nome é parte do contrato de autoria a partir do momento em que alguém o escreve num import, e por
+ * isso ele deixou de ser uma string solta aqui dentro.
+ */
+export declare const FUNCTIONS_PACKAGE_NAME = "microteia-functions";
+export declare const OFFICE_SUBPATH = "office";
+export declare const OFFICE_MODULE = "microteia-functions/office";
 /**
  * As dependências são copiadas INTACTAS do `functions/package.json` do repositório, para que o
  * `package-lock.json` que viaja junto continue válido. O que muda é só o entrypoint (passa a ser o
- * `index.js` que soma kernel e custom) e o `build`, que agora compila apenas `custom/`.
+ * `index.js` que soma kernel e custom), o `build`, que agora compila apenas `custom/`, e o `exports`,
+ * que abre a superfície curada para o `custom/` sem custar uma dependência.
  */
 /**
  * A `version` não é enfeite: sem ela o npm não consegue formar `nome@versão` e todo aviso dele sobre

package/lib/vendor/packageTemplates.js

@@ -24,10 +24,21 @@ export const packageFirebaseJson = (hosting) => JSON.stringify({
         headers: hosting.headers,
     },
 }, null, 2) + '\n';
+/**
+ * O nome do pacote de functions da instalação, e o subcaminho da superfície curada que a Cloud Function
+ * do ESCRITÓRIO importa dele: `import { forInstalledExtension } from 'microteia-functions/office'`.
+ *
+ * O nome é parte do contrato de autoria a partir do momento em que alguém o escreve num import, e por
+ * isso ele deixou de ser uma string solta aqui dentro.
+ */
+export const FUNCTIONS_PACKAGE_NAME = 'microteia-functions';
+export const OFFICE_SUBPATH = 'office';
+export const OFFICE_MODULE = `${FUNCTIONS_PACKAGE_NAME}/${OFFICE_SUBPATH}`;
 /**
  * As dependências são copiadas INTACTAS do `functions/package.json` do repositório, para que o
  * `package-lock.json` que viaja junto continue válido. O que muda é só o entrypoint (passa a ser o
- * `index.js` que soma kernel e custom) e o `build`, que agora compila apenas `custom/`.
+ * `index.js` que soma kernel e custom), o `build`, que agora compila apenas `custom/`, e o `exports`,
+ * que abre a superfície curada para o `custom/` sem custar uma dependência.
  */
 /**
  * A `version` não é enfeite: sem ela o npm não consegue formar `nome@versão` e todo aviso dele sobre
@@ -40,10 +51,29 @@ export const packageFirebaseJson = (hosting) => JSON.stringify({
  * o Firebase — o preço errado pela linha de saída.
  */
 export const packageFunctionsPackageJson = (source, version) => JSON.stringify({
-    name: 'microteia-functions',
+    name: FUNCTIONS_PACKAGE_NAME,
     version,
     private: true,
     main: 'index.js',
+    /**
+     * O `exports` está aqui por UMA razão, e ela não é organização: é ele que faz a auto-referência de
+     * pacote funcionar. Sem ele, uma Cloud Function do escritório em `custom/` não tem como importar nada
+     * da plataforma — não há `node_modules` que a contenha, e um caminho relativo dependeria de onde o
+     * arquivo foi montado, que é justamente o que muda entre escrever e deployar.
+     *
+     * Com ele, `require('${FUNCTIONS_PACKAGE_NAME}/office')` resolve de dentro do próprio pacote. É por
+     * isso que não há dependência nova nem alteração no `package-lock.json` que viaja ao lado.
+     *
+     * O `.` continua sendo o `index.js`: é ele que o Firebase carrega, e restringir os subcaminhos sem
+     * declará-lo tiraria a plataforma do ar inteira.
+     */
+    exports: {
+        '.': './index.js',
+        [`./${OFFICE_SUBPATH}`]: {
+            types: `./lib/${OFFICE_SUBPATH}/index.d.ts`,
+            default: `./lib/${OFFICE_SUBPATH}/index.js`,
+        },
+    },
     engines: source.engines ?? { node: '22' },
     scripts: {
         build: 'tsc -p custom/tsconfig.json',
@@ -74,6 +104,16 @@ export const packageCustomTsconfig = () => JSON.stringify({
     compilerOptions: {
         module: 'commonjs',
         moduleResolution: 'node',
+        /**
+         * O `paths` só resolve TIPO; o `require` emitido continua sendo `microteia-functions/office`, e é o
+         * `exports` do pacote que o resolve em execução. Os dois lados são necessários porque o
+         * `moduleResolution: 'node'` é anterior ao `exports` e não o lê — e trocá-lo por `node16` mudaria,
+         * de quebra, como TODO import do escritório resolve.
+         *
+         * Sem `baseUrl` de propósito: o `paths` relativo ao tsconfig basta desde o TypeScript 4.1, e um
+         * `baseUrl` faria qualquer arquivo de `src/` virar um módulo de nome curto por acidente.
+         */
+        paths: { [OFFICE_MODULE]: [`../lib/${OFFICE_SUBPATH}/index.d.ts`] },
         target: 'es2022',
         lib: ['ES2022'],
         types: ['node'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.10.0",
+  "version": "2.19.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",