@microteia/console 2.8.0 → 2.18.0

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/kernel/manifest.d.ts

@@ -44,6 +44,16 @@ export interface KernelManifest {
     baselineIndexes: FirestoreIndexSpec[];
     /** Ausente nos pacotes anteriores a 7.51.0, que não conheciam a verificação de alcance. */
     callables?: string[];
+    /**
+     * Os pontos de extensão que fazem efeito ANTES do login. É contra esta lista que o `deploy` decide
+     * se um pacote carimbado tem o que fazer no boot — carimbar um que não contribua para nenhum deles
+     * o carregaria sem efeito, e quem o carimbou acreditaria que está no ar.
+     *
+     * Ela é DERIVADA do kernel e viaja no manifesto justamente para o Console não a conhecer de cor: o
+     * Console é versionado separadamente, e uma cópia aqui passaria a descrever o contrato de outra
+     * versão em silêncio. Ausente nos pacotes anteriores às extensões carimbadas.
+     */
+    preLoginPoints?: string[];
     backendParameters: BackendParameter[];
     manualPrerequisites: KernelPrerequisite[];
     /**
@@ -135,4 +145,10 @@ export declare const callableFunctionNames: (source: string) => string[];
 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;
+/**
+ * Os pontos que valem antes do login, lidos de `domain/schema/plugin/preLoginPoints.ts`. Lista vazia é
+ * recusada em vez de aceita: um pacote sem nenhum ponto pré-login recusaria todo carimbo, e a causa
+ * (o parser não achou nada) não teria nada a ver com o sintoma.
+ */
+export declare const parsePreLoginPoints: (source: string) => string[];
 export declare const parseKernelVersion: (source: string) => string;

package/lib/kernel/manifest.js

@@ -137,6 +137,22 @@ export const compareVersions = (left, right) => {
     }
     return 0;
 };
+/**
+ * Os pontos que valem antes do login, lidos de `domain/schema/plugin/preLoginPoints.ts`. Lista vazia é
+ * recusada em vez de aceita: um pacote sem nenhum ponto pré-login recusaria todo carimbo, e a causa
+ * (o parser não achou nada) não teria nada a ver com o sintoma.
+ */
+export const parsePreLoginPoints = (source) => {
+    const block = source.match(/PRE_LOGIN_POINTS[^=]*=\s*\[([^\]]*)\]/);
+    if (block === null) {
+        throw new Error('PRE_LOGIN_POINTS not found in domain/schema/plugin/preLoginPoints.ts');
+    }
+    const points = [...block[1].matchAll(/'([^']+)'/g)].map((match) => match[1]);
+    if (points.length === 0) {
+        throw new Error('PRE_LOGIN_POINTS is empty in domain/schema/plugin/preLoginPoints.ts');
+    }
+    return points;
+};
 export const parseKernelVersion = (source) => {
     const match = source.match(/KERNEL_VERSION\s*=\s*'([^']+)'/);
     if (match === null)

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.8.0";
+export declare const CLI_VERSION = "2.18.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.8.0';
+export const CLI_VERSION = '2.18.0';

package/lib/vendor/exampleSources.js

@@ -31,7 +31,9 @@ export const EXAMPLE_SOURCES = {
  * extensão tem a sua pasta — aqui elas moram num diretório comum, com um nível a mais.
  */
 export const rewriteImports = (source) => source.replace(/from '(\.[^']*)'/g, (match, specifier) => {
-    if (/(^|\/)contributionBuilders$/.test(specifier) || specifier.includes('domain/')) {
+    if (/(^|\/)contributionBuilders$/.test(specifier)
+        || specifier.includes('domain/')
+        || specifier.includes('sdk/')) {
         return "from '@microteia/sdk'";
     }
     // `./views/<plugin>/Nome.tsx?raw` -> `./views/Nome.tsx?raw`
@@ -44,8 +46,10 @@ const HEADER = (id) => `// Example: a Microteia first-party extension, as SOURCE
 //
 //     npx microteia-plugin build ${id}/plugin.ts
 //
-// The only difference from how it is written inside Microteia is the import path: there it reaches into
-// the kernel tree, here everything comes from '@microteia/sdk'.
+// Two things differ from how you would write the same extension. The imports: inside Microteia they
+// reach into the kernel tree, here everything comes from '@microteia/sdk'. And the view sources: these
+// travel as TEXT and are merged by 'mergeViewSources', because the platform bundles them; you point at
+// the files with 'sourceFile' and the compiler merges them for you. See AUTHORING.md, section 7.
 
 `;
 /**

package/lib/vendor/installationDocs.js

@@ -94,6 +94,7 @@ const commandRows = () => [
     '| `microteia provision [--prune] [--all]` | Gives installed extensions the functions and indexes they ask for |',
     '| `microteia connect --project <id>` | Binds this installation to a Firebase project you own |',
     '| `microteia plugin-init` | Prepares `extensions/` for authoring in TypeScript |',
+    '| `microteia export-catalog --tenant <id>` | Writes what an office has — screens, lists, installed extensions — into `extensions/`, so the authoring tools can see it. Reads only; with no `--tenant` it lists the offices. The file is a snapshot and is git-ignored: it carries names the office typed |',
 ].join('\n');
 /**
  * O documento técnico. SOBREPOSTO a cada `unpack`, e por isso é onde o detalhe que acompanha a versão
@@ -145,6 +146,23 @@ it is what makes an upgrade trustworthy, and the reason your files are elsewhere
 
 ${commandRows()}
 
+### Signing in before there is an organization
+
+The sign-in screen runs above the organization: there is no tenant there, so nothing an organization
+installed can reach it. That is why \`login.extensions\` in \`microteia.yaml\` exists — it lists compiled
+extension packages that \`deploy\` stamps into the site itself, and it is how a corporate SSO, or your own
+mark on the sign-in screen, gets there.
+
+Two things follow, and both are deliberate:
+
+- **Nothing stamped runs JavaScript.** The packages load untrusted, so only declarations apply. That is
+  what lets you put an SSO live without anyone reviewing code.
+- **Stamping is not installing.** A stamped package applies before sign-in only; inside the organization
+  what applies is what the organization installed, from the Extensions screen. To have both, do both.
+
+\`deploy\` refuses a package that contributes to nothing which works before sign-in, rather than stamping
+it: it would load with no effect, and you would believe it was live.
+
 \`unpack\` and \`deploy\` are separate so that taking a new version does not oblige you to publish
 everything, and so that there is a moment between the two to fill in a setting the new version asks for.
 

package/lib/vendor/pack.js

@@ -4,7 +4,7 @@ import { flagValue, hasFlag } from '../shared/args.js';
 import { repoRoot } from '../shared/paths.js';
 import { run } from '../shared/run.js';
 import { blank, bullets, heading, info, step, success } from '../shared/ui.js';
-import { DEFAULT_FUNCTIONS_REGION, KERNEL_COMPONENTS, KERNEL_DISTRIBUTION_ID, MANUAL_PREREQUISITES, MINIMUM_CLI_VERSION, REQUIRED_NODE_VERSION, callableFunctionNames, declaredParametersIn, exportedFunctionNames, parseKernelVersion, } from '../kernel/manifest.js';
+import { DEFAULT_FUNCTIONS_REGION, KERNEL_COMPONENTS, KERNEL_DISTRIBUTION_ID, MANUAL_PREREQUISITES, MINIMUM_CLI_VERSION, REQUIRED_NODE_VERSION, callableFunctionNames, declaredParametersIn, exportedFunctionNames, parseKernelVersion, parsePreLoginPoints, } from '../kernel/manifest.js';
 import { digestOfFile } from '../shared/digest.js';
 import { kernelTarballName } from '../kernel/channel.js';
 import { baselineFunctionsOf, baselineIndexesOf, claimProblems, claimsFromTemplates, } from '../kernel/backendShape.js';
@@ -123,6 +123,7 @@ export const pack = async (args) => {
      */
     const changelog = await readChangelog(root, KERNEL_CHANGELOG, version);
     const kernelVersion = parseKernelVersion(await readFile(join(root, 'src/domain/schema/plugin/kernelVersion.ts'), 'utf8'));
+    const preLoginPoints = parsePreLoginPoints(await readFile(join(root, 'src/domain/schema/plugin/preLoginPoints.ts'), 'utf8'));
     const functionNames = exportedFunctionNames(await readFile(join(root, 'functions/src/index.ts'), 'utf8'));
     const scan = await scanBackendSources(join(root, 'functions/src'));
     const backendParameters = scan.parameters;
@@ -225,6 +226,7 @@ export const pack = async (args) => {
         baselineFunctions,
         baselineIndexes,
         callables,
+        preLoginPoints,
         backendParameters,
         manualPrerequisites: MANUAL_PREREQUISITES,
         sdk,

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.8.0",
+  "version": "2.18.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",