@microteia/console 2.19.0 → 2.21.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,33 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.21.0] — 2026-09-09
+
+- fix(cli/pack): reading-only examples are left out of the first-party backend accounting.
+  `extension-templates/` holds two kinds of package with the same shape and different owners — the
+  first-party extensions, whose Cloud Functions this kernel compiles and deploys, and the examples,
+  whose backend belongs to whoever installs them. The pack derives its baseline as
+  `all functions − claimed`, so the first example to teach Cloud Functions would have aborted every
+  publish by claiming a name that is not here, and a name that WAS here would have been taken out of
+  the kernel baseline by a mere template. `firstPartyTemplates` is now the single door onto that
+  directory, and `READING_ONLY_EXAMPLES` is derived from where an example's source lives rather than
+  kept as a second list.
+- feat(cli/vendor): `stageExamples` carries `functions/` and `scripts/` beside `views/`, and an
+  example whose source is a DIRECTORY takes `plugin.ts` as its entry. Without both, an example could
+  not teach a Cloud Function or a sandbox script — the two files simply would not travel.
+- fix(cli/vendor): `rewriteImports` sends the node-only modules to `@microteia/sdk/node` instead of to
+  the isomorphic barrel, which is where `transpileScriptSource` deliberately is not. The symptom
+  would have been in the office of whoever installed, not here.
+- fix(cli/vendor): the `MICROTEIA.md` it writes derives its build command from the examples actually
+  present. It named `examples/pessoa`, which left the repository with the office extensions — a
+  generated document telling the reader to compile something that is not there.
+
+#### [2.20.0] — 2026-09-01
+
+- feat(cli/export-catalog): the snapshot carries what each installed extension declares in `manifest.exports` — the artifacts another extension may reference as `<extension-id>/<source-id>`. Whoever authors outside the office knew an extension was installed and had no way to learn the name of anything inside it, so the reference could be written by hand and never discovered. Each entry carries the id, the artifact's name, and its `kind`, which is the part that decides where the reference fits: a script goes in `scriptId`, an automation in `targetWorkflowId`. What the artifact DOES still never travels — the steps and the code are behaviour, and the snapshot is shape.
+- feat(cli/export-catalog): a declared export that matches no artifact in the package travels as `unknown` rather than being dropped. The install gate checks the LIST, so a reference to it would be accepted there and fail only on the step's first run; saying it is better than hiding it.
+- feat(cli/export-catalog): `exports` is written for every extension, empty list included. A present-and-empty list is the answer "this extension exports nothing"; an absent key is the silence of a Console older than the field, and the kernel tells the two apart instead of reading absence as a claim.
+
 #### [2.19.0] — 2026-08-28
 
 - fix(cli/deploy): the installation gate is charged against the functions that are GOING UP, not against every source found on disk. It lived in `functionProblems` — the door that answers "can this set be assembled?" — and that door reads every `extensions/<x>/functions/` directory that exists, including one left behind by an extension that was uninstalled and removed. The result was `microteia deploy` refusing in full — hosting, rules and indexes with it — over a callable no command would have deployed. `gateProblems` now carries the function's name, and `gateProblemsFor` filters by what is being deployed.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.19.0
+# Microteia Console 2.21.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.

package/lib/console/exportCatalog.d.ts

@@ -76,11 +76,33 @@ export interface CatalogListExport {
     label: string;
     ownerPluginId?: string;
 }
+/**
+ * Um artefato que a extensão declara em `manifest.exports` — a superfície que outra extensão pode
+ * referenciar como `<pluginId>/<sourceId>`.
+ *
+ * O `kind` viaja porque é ele que decide ONDE a referência cabe: script em `scriptId`, automação em
+ * `targetWorkflowId`. `unknown` é o export declarado que não casa com artefato nenhum do pacote —
+ * dizê-lo é melhor que omiti-lo, porque uma referência a ele passaria no portão da instalação, que
+ * confere a LISTA, e falharia só na primeira execução.
+ *
+ * O que NÃO viaja é o que o artefato faz: os passos e o código são comportamento, e o retrato é
+ * esquema. O nome e o tipo são contrato.
+ */
+export interface CatalogExtensionExportedArtifact {
+    id: string;
+    kind: 'workflow' | 'action' | 'script' | 'unknown';
+    name: string;
+}
 export interface CatalogExtensionExport {
     id: string;
     name: string;
     version: string;
     active: boolean;
+    /**
+     * Sempre escrita, mesmo vazia. É a lista PRESENTE e vazia que diz "esta extensão não exporta nada";
+     * a chave ausente é o silêncio de um Console anterior a este campo, e o kernel distingue as duas.
+     */
+    exports: CatalogExtensionExportedArtifact[];
 }
 export interface CatalogExport {
     version: number;

package/lib/console/exportCatalog.js

@@ -46,6 +46,38 @@ const asRecord = (value) => (typeof value === 'object' && value !== null && !Arr
     ? value
     : undefined);
 const FIELD_ORIGINS = ['builtin', 'plugin', 'design'];
+/**
+ * A superfície exportada de uma cópia instalada: os ids de `manifest.exports`, cada um casado com o
+ * artefato do pacote que o atende, para ganhar tipo e nome.
+ *
+ * O Console não alcança `src/` — logo não há `MarketplacePlugin` tipado aqui, e a leitura é do
+ * documento cru, como todo o resto deste arquivo. Um export que não casa com nada continua na lista
+ * como `unknown`: a extensão está declarando algo que não entrega, e esconder isso do autor apenas
+ * adia a descoberta para a primeira execução.
+ */
+const exportedArtifacts = (extension) => {
+    const declared = extension.manifest?.exports;
+    if (!Array.isArray(declared))
+        return [];
+    const pkg = asRecord(extension.data.package) ?? {};
+    const named = new Map();
+    const collect = (raw, kind) => {
+        for (const one of Array.isArray(raw) ? raw : []) {
+            const record = asRecord(one);
+            const id = text(record?.templateId);
+            if (id === undefined || named.has(id))
+                continue;
+            named.set(id, { id, kind, name: text(record?.name) ?? text(record?.title) ?? id });
+        }
+    };
+    collect(pkg.workflows, 'workflow');
+    collect(pkg.actions, 'action');
+    collect(pkg.scripts, 'script');
+    return declared
+        .filter((id) => typeof id === 'string' && id !== '')
+        .map((id) => named.get(id) ?? { id, kind: 'unknown', name: id })
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+};
 /**
  * A mesma dedução que a aplicação faz ao ler a tela (`screenDefinitionMapper.ts`): o `origin` gravado
  * quando ele existe, senão `plugin` para quem tem dono e `design` para o que o escritório criou. Ela é
@@ -135,7 +167,13 @@ export const buildCatalogExport = (input) => ({
     kernelVersion: input.kernelVersion,
     consoleVersion: CLI_VERSION,
     extensions: input.extensions
-        .map((one) => ({ id: one.id, name: one.name, version: one.version, active: one.active }))
+        .map((one) => ({
+        id: one.id,
+        name: one.name,
+        version: one.version,
+        active: one.active,
+        exports: exportedArtifacts(one),
+    }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
     screens: input.screens
         .filter((document) => document.data.enabled !== false)
@@ -252,13 +290,16 @@ export const exportCatalog = async (args) => {
         + `${document.lookups.length} list(s), ${document.tagLists.length} tag list(s)`);
     info(`  ${fromExtensions} screen(s) come from the ${document.extensions.length} installed extension(s); `
         + `the rest the office built itself.`);
+    const exported = document.extensions.reduce((total, one) => total + one.exports.length, 0);
+    info(`  ${exported} artifact(s) are declared for other extensions to reference as <extension-id>/<id>.`);
     blank();
     await checkIgnored(directory);
     info('It is a SNAPSHOT, and it says so: the authoring tools report when it was taken and warn when it');
     info('is old. Nothing keeps it in step with the office — run this again after screens change there.');
     blank();
     info('What it deliberately leaves out: records, the values inside a list of options or a tag list,');
-    info('members and permissions, workflows, scripts, actions, secrets and settings. It describes what');
-    info('the entities ARE, and nothing an office typed into them.');
+    info('members and permissions, what a workflow, script or action DOES, secrets and settings. It');
+    info('describes what the entities ARE, and nothing an office typed into them. What each extension');
+    info('declares in "exports" travels: that is the surface another extension may reference.');
     blank();
 };

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.19.0";
+export declare const CLI_VERSION = "2.21.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.19.0';
+export const CLI_VERSION = '2.21.0';

package/lib/vendor/exampleSources.d.ts

@@ -1,19 +1,33 @@
 /**
- * As extensões de primeira parte, empacotadas como FONTE — `plugin.ts` e as views em `.tsx` —, uma pasta
- * por extensão.
+ * Arquivo distribuído → módulo de origem, relativo a `src/plugins/marketplace/`. O nome da pasta do
+ * exemplo é o do `.json`, sem extensão.
  *
- * Viajavam como `.json`. Um `.json` de 90 KB não ensina nada: é o artefato, e quem abre não vê como se
- * chega nele. O que ensina é a fonte, e ela já viaja de qualquer forma — o código das views está dentro
- * do `.json`, em string. Passar a mandar o `.ts` não expõe nada novo; expõe de forma legível o que já ia.
+ * Há DUAS formas de origem, e a diferença não é de estilo: é de quem o módulo é.
  *
- * A única transformação é de IMPORT: neste repositório um plugin importa `../../domain/entities/...` e
- * `../contributionBuilders`; do lado do escritório, tudo isso é `@microteia/sdk`. Todo símbolo usado
- * pelos doze está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
- * COMPILA cada exemplo reescrito e exige que o `.json` saia byte a byte igual ao versionado. Um símbolo
- * que faltasse no barril reprovaria ali, e não no escritório de alguém.
+ * - **Um arquivo** (`automation.ts`) — a extensão mora na raiz do marketplace porque ela é, ou já foi,
+ *   uma extensão de PRIMEIRA PARTE do catálogo embutido. Os vizinhos que ela importa são descobertos
+ *   por `siblingModules`, e as views dela ficam em `views/<módulo>/`.
+ * - **Um diretório** (`examples/report-example`) — a extensão existe SÓ para ser lida. Nada dela entra
+ *   no `MARKETPLACE_CATALOG`, então ela não tem por que ocupar a raiz do marketplace junto das que
+ *   entram: ali as cinco de primeira parte se perderiam no meio de doze moldes. Tudo o que é dela mora
+ *   na pasta dela — o `plugin.ts`, os catálogos de mensagem e as `views/`.
  */
-/** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
 export declare const EXAMPLE_SOURCES: Record<string, string>;
+/**
+ * Os exemplos que existem SÓ para ser lidos — os que não estão no catálogo embutido.
+ *
+ * A pergunta que eles respondem é do `pack`: de quem é o backend que este repositório sobe. Uma
+ * extensão de primeira parte que declare `manifest.backend` reivindica uma function que o kernel
+ * compila e deploya, e o `pack` confere isso — reivindicar um nome que não existe aborta o
+ * empacotamento, e reivindicar um que existe o TIRA da baseline. Um exemplo não é nada disso: o
+ * `functions/` dele viaja como fonte para ser lido, e quem o instalar de verdade constrói o próprio.
+ * Sem esta distinção, o primeiro exemplo a ensinar Cloud Functions reprovaria toda publicação.
+ *
+ * É DERIVADA da forma da origem, e não uma segunda lista a manter: morar em `examples/` é
+ * exatamente o que significa não estar no catálogo embutido. As cinco de primeira parte moram na raiz
+ * do marketplace porque o bundle as carrega, e é por isso que elas continuam sendo cobradas.
+ */
+export declare const READING_ONLY_EXAMPLES: ReadonlySet<string>;
 /**
  * Reescreve os imports de um plugin para a forma que o escritório usa.
  *

package/lib/vendor/exampleSources.js

@@ -10,19 +10,70 @@ import { join } from 'node:path';
  *
  * A única transformação é de IMPORT: neste repositório um plugin importa `../../domain/entities/...` e
  * `../contributionBuilders`; do lado do escritório, tudo isso é `@microteia/sdk`. Todo símbolo usado
- * pelos doze está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
+ * por eles está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
  * COMPILA cada exemplo reescrito e exige que o `.json` saia byte a byte igual ao versionado. Um símbolo
  * que faltasse no barril reprovaria ali, e não no escritório de alguém.
  */
-/** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
+/** A pasta, dentro do marketplace, em que mora um exemplo que existe só para ser lido. */
+const EXAMPLES_DIR = 'examples';
+/**
+ * Arquivo distribuído → módulo de origem, relativo a `src/plugins/marketplace/`. O nome da pasta do
+ * exemplo é o do `.json`, sem extensão.
+ *
+ * Há DUAS formas de origem, e a diferença não é de estilo: é de quem o módulo é.
+ *
+ * - **Um arquivo** (`automation.ts`) — a extensão mora na raiz do marketplace porque ela é, ou já foi,
+ *   uma extensão de PRIMEIRA PARTE do catálogo embutido. Os vizinhos que ela importa são descobertos
+ *   por `siblingModules`, e as views dela ficam em `views/<módulo>/`.
+ * - **Um diretório** (`examples/report-example`) — a extensão existe SÓ para ser lida. Nada dela entra
+ *   no `MARKETPLACE_CATALOG`, então ela não tem por que ocupar a raiz do marketplace junto das que
+ *   entram: ali as cinco de primeira parte se perderiam no meio de doze moldes. Tudo o que é dela mora
+ *   na pasta dela — o `plugin.ts`, os catálogos de mensagem e as `views/`.
+ */
 export const EXAMPLE_SOURCES = {
-    'automation-example': 'automation.ts',
+    'automation-example': 'examples/automation-example',
     brasil: 'brasil.ts',
     calendar: 'calendar.ts',
     dashboard: 'dashboard.ts',
     'locale-pt-br': 'localePtBr',
     news: 'news.ts',
+    'report-example': 'examples/report-example',
+    'widget-example': 'examples/widget-example',
+    'access-example': 'examples/access-example',
+    'backend-example': 'examples/backend-example',
+    'library-example': 'examples/library-example',
+    'consumer-example': 'examples/consumer-example',
+    'patch-example': 'examples/patch-example',
+    'theme-example': 'examples/theme-example',
+    'auth-example': 'examples/auth-example',
+    'command-example': 'examples/command-example',
+    'settings-example': 'examples/settings-example',
 };
+/**
+ * Os exemplos que existem SÓ para ser lidos — os que não estão no catálogo embutido.
+ *
+ * A pergunta que eles respondem é do `pack`: de quem é o backend que este repositório sobe. Uma
+ * extensão de primeira parte que declare `manifest.backend` reivindica uma function que o kernel
+ * compila e deploya, e o `pack` confere isso — reivindicar um nome que não existe aborta o
+ * empacotamento, e reivindicar um que existe o TIRA da baseline. Um exemplo não é nada disso: o
+ * `functions/` dele viaja como fonte para ser lido, e quem o instalar de verdade constrói o próprio.
+ * Sem esta distinção, o primeiro exemplo a ensinar Cloud Functions reprovaria toda publicação.
+ *
+ * É DERIVADA da forma da origem, e não uma segunda lista a manter: morar em `examples/` é
+ * exatamente o que significa não estar no catálogo embutido. As cinco de primeira parte moram na raiz
+ * do marketplace porque o bundle as carrega, e é por isso que elas continuam sendo cobradas.
+ */
+export const READING_ONLY_EXAMPLES = new Set(Object.entries(EXAMPLE_SOURCES)
+    .filter(([, origin]) => origin.startsWith(`${EXAMPLES_DIR}/`))
+    .map(([id]) => id));
+/**
+ * Os módulos do kernel cuja casa, para quem escreve de fora, é `@microteia/sdk/node` — a entrada de
+ * FERRAMENTA do pacote, e não o barril isomórfico.
+ *
+ * `scriptSource` está aqui porque um `Script` viaja com `sourceTs` E `compiledJs`, e o sandbox nunca
+ * transpila: quem empacota precisa produzir o segundo, com o MESMO transpilador que o runtime usa.
+ */
+const NODE_ONLY_MODULES = ['sdk/node/', 'domain/services/scriptSource'];
 /**
  * Reescreve os imports de um plugin para a forma que o escritório usa.
  *
@@ -31,6 +82,14 @@ 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) => {
+    // A FERRAMENTA vem antes da superfície, e a ordem é o ponto: estes caminhos também casariam com as
+    // regras genéricas abaixo, que os mandariam para o barril isomórfico — onde `transpileScriptSource`
+    // NÃO está, de propósito, porque ele arrasta o `sucrase` e `@microteia/sdk` é a superfície que não
+    // arrasta nada. Do lado do escritório ele vem de `@microteia/sdk/node`, que é outra entrada do
+    // mesmo pacote. O sintoma seria no escritório de quem instalou, não aqui, se o round-trip byte a
+    // byte não compilasse cada exemplo reescrito.
+    if (NODE_ONLY_MODULES.some((one) => specifier.includes(one)))
+        return "from '@microteia/sdk/node'";
     if (/(^|\/)contributionBuilders$/.test(specifier)
         || specifier.includes('domain/')
         || specifier.includes('sdk/')) {
@@ -81,9 +140,18 @@ const siblingModules = async (marketplace, entry) => {
     }
     return collected;
 };
-const viewFiles = async (viewsDir) => {
+/**
+ * Os arquivos de uma pasta do exemplo — `views/` ou `functions/` —, e o teste deles COM eles, de
+ * propósito. Pasta ausente é lista vazia, nunca erro: nem todo exemplo tem as duas.
+ *
+ * O `.rules.test.ts` ao lado de um `.rules.ts` é material didático: é onde se vê que a regra de uma
+ * view pode ser extraída e exercitada sem montar React nenhum, que é exatamente o que o `AGENTS.md`
+ * pede de quem escreve aqui. O `.test.ts` da RAIZ do módulo é outra coisa — aquele é nosso, sobre a
+ * nossa extensão — e é por isso que só ele é filtrado, no laço de baixo.
+ */
+const sourceFilesIn = async (folder) => {
     try {
-        return (await readdir(viewsDir)).filter((name) => name.endsWith('.tsx') || name.endsWith('.ts'));
+        return (await readdir(folder)).filter((name) => name.endsWith('.tsx') || name.endsWith('.ts'));
     }
     catch {
         return [];
@@ -107,7 +175,7 @@ export const stageExamples = async (repo, target) => {
             }
             const plugin = origin.replace(/\.ts$/, '');
             const views = join(marketplace, 'views', plugin);
-            const files = await viewFiles(views);
+            const files = await sourceFilesIn(views);
             if (files.length > 0)
                 await mkdir(join(directory, 'views'), { recursive: true });
             for (const name of files) {
@@ -115,14 +183,34 @@ export const stageExamples = async (repo, target) => {
             }
         }
         else {
-            // Extensão que é um DIRETÓRIO (o pacote de idioma, com um arquivo por namespace). O `index.ts`
-            // vira `plugin.ts`; os demais são vizinhos dele e os imports relativos seguem valendo.
-            for (const name of await readdir(join(marketplace, origin))) {
+            // Extensão que é um DIRETÓRIO: o exemplo de leitura, cuja entrada é `plugin.ts`, e o pacote de
+            // idioma, cuja entrada é `index.ts` porque ele é um módulo de primeira parte antes de ser um
+            // exemplo. A entrada vira `plugin.ts` no destino nos dois casos — é o nome que o autor compila —
+            // e os demais `.ts` são vizinhos dela, com os imports relativos seguindo valendo.
+            const source = join(marketplace, origin);
+            const names = await readdir(source);
+            const entry = names.includes('plugin.ts') ? 'plugin.ts' : 'index.ts';
+            for (const name of names) {
                 if (!name.endsWith('.ts') || name.endsWith('.test.ts'))
                     continue;
-                const source = rewriteImports(await readFile(join(marketplace, origin, name), 'utf8'));
-                const isEntry = name === 'index.ts';
-                await writeFile(join(directory, isEntry ? 'plugin.ts' : name), isEntry ? HEADER(id) + source : source);
+                const text = rewriteImports(await readFile(join(source, name), 'utf8'));
+                const isEntry = name === entry;
+                await writeFile(join(directory, isEntry ? 'plugin.ts' : name), isEntry ? HEADER(id) + text : text);
+            }
+            // As views, as Cloud Functions e os scripts de um exemplo moram DENTRO dele, e não em
+            // `views/<módulo>/`: a pasta é o pacote, exatamente como do lado do escritório. `functions/` e
+            // `scripts/` viajam VERBATIM — a primeira já é escrita contra `microteia-functions/office` e
+            // `firebase-functions`, que são os nomes que valem lá, e a segunda não importa nada: o script
+            // roda no sandbox, contra globais que só existem lá dentro.
+            for (const folder of ['views', 'functions', 'scripts']) {
+                const from = join(source, folder);
+                const files = await sourceFilesIn(from);
+                if (files.length === 0)
+                    continue;
+                await mkdir(join(directory, folder), { recursive: true });
+                for (const name of files) {
+                    await writeFile(join(directory, folder, name), await readFile(join(from, name), 'utf8'));
+                }
             }
         }
         written.push(id);

package/lib/vendor/firstPartyTemplates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Os `extension-templates/*.json` cujo backend é DESTE repositório — a única porta para essa pergunta.
+ *
+ * `extension-templates/` guarda duas coisas com a mesma forma e donos diferentes: as extensões de
+ * primeira parte, que viajam no bundle e cujas Cloud Functions o kernel compila e deploya, e os
+ * exemplos, que viajam como fonte para serem lidos e cujo backend pertence a quem os instalar. A conta
+ * do `pack` — baseline = todas as functions menos as reivindicadas — só faz sentido sobre as primeiras.
+ *
+ * A porta é única porque a pergunta já estava em dois lugares: o `pack` e o teste que guarda o `pack`.
+ * Dois leitores do mesmo diretório com filtros diferentes é como um portão passa a aprovar o que ele
+ * existe para reprovar — aqui, o exemplo que ensina Cloud Functions abortando toda publicação, ou uma
+ * function saindo da baseline do kernel porque um MOLDE a reivindicou.
+ */
+export declare const firstPartyTemplates: <T>(root: string) => T[];

package/lib/vendor/firstPartyTemplates.js

@@ -0,0 +1,23 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { READING_ONLY_EXAMPLES } from './exampleSources.js';
+/**
+ * Os `extension-templates/*.json` cujo backend é DESTE repositório — a única porta para essa pergunta.
+ *
+ * `extension-templates/` guarda duas coisas com a mesma forma e donos diferentes: as extensões de
+ * primeira parte, que viajam no bundle e cujas Cloud Functions o kernel compila e deploya, e os
+ * exemplos, que viajam como fonte para serem lidos e cujo backend pertence a quem os instalar. A conta
+ * do `pack` — baseline = todas as functions menos as reivindicadas — só faz sentido sobre as primeiras.
+ *
+ * A porta é única porque a pergunta já estava em dois lugares: o `pack` e o teste que guarda o `pack`.
+ * Dois leitores do mesmo diretório com filtros diferentes é como um portão passa a aprovar o que ele
+ * existe para reprovar — aqui, o exemplo que ensina Cloud Functions abortando toda publicação, ou uma
+ * function saindo da baseline do kernel porque um MOLDE a reivindicou.
+ */
+export const firstPartyTemplates = (root) => {
+    const dir = join(root, 'extension-templates');
+    return readdirSync(dir)
+        .filter((file) => file.endsWith('.json'))
+        .filter((file) => !READING_ONLY_EXAMPLES.has(basename(file, '.json')))
+        .map((file) => JSON.parse(readFileSync(join(dir, file), 'utf8')));
+};

package/lib/vendor/installationDocs.js

@@ -254,7 +254,7 @@ ${examples.length === 0 ? '_None in this package._' : examples.map((id) => `- \`
 Each is the real source of an extension that ships with Microteia. Build any of them and you get the
 same \`.json\` the platform installs:
 
-    npx microteia-plugin build examples/pessoa/plugin.ts
+    npx microteia-plugin build examples/${examples[0] ?? '<example>'}/plugin.ts
 
 ## 6. An AI assistant in this directory
 

package/lib/vendor/pack.js

@@ -13,6 +13,7 @@ import { KERNEL_CHANGELOG, readChangelog } from './changelogs.js';
 import { assertInsideRepository } from './repository.js';
 import { SDK_TARBALL } from './pluginWorkspaceTemplates.js';
 import { stageExamples } from './exampleSources.js';
+import { firstPartyTemplates } from './firstPartyTemplates.js';
 import { packageCustomIndexTs, packageCustomTsconfig, packageFirebaseJson, packageFunctionsIndexJs, packageFunctionsPackageJson, } from './packageTemplates.js';
 /**
  * `dist` é um modo do Vite para o qual NÃO existe `.env.dist`. É isso que garante um bundle sem
@@ -23,13 +24,13 @@ const DISTRIBUTION_TARGET = 'dist';
  * As exigências de backend das extensões de PRIMEIRA PARTE saem dos `extension-templates/*.json`, que
  * são gerados dos `.ts` e conferidos pelo `verify-extensions` que o gate de qualidade acima já roda.
  * Ler o `.json` gerado em vez do `.ts` evita carregar o Vite aqui só para avaliar um módulo.
+ *
+ * Os exemplos que só viajam para ser lidos ficam de FORA (`READING_ONLY_EXAMPLES`), e o motivo está
+ * escrito lá: o backend de um exemplo não é deste repositório. Cobrá-lo aqui faria o exemplo que
+ * ensina Cloud Functions abortar toda publicação — e, se a function existisse, a reivindicação a
+ * tiraria da baseline do kernel, que é o oposto exato do que um exemplo deve provocar.
  */
-const firstPartyClaims = async (root) => {
-    const dir = join(root, 'extension-templates');
-    const files = (await readdir(dir)).filter((file) => file.endsWith('.json'));
-    const templates = await Promise.all(files.map((file) => readJson(join(dir, file))));
-    return claimsFromTemplates(templates);
-};
+const firstPartyClaims = (root) => claimsFromTemplates(firstPartyTemplates(root));
 const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
 /**
  * Os `defineString` e as callables estão espalhados pelos handlers, não num arquivo só — então a
@@ -131,7 +132,7 @@ export const pack = async (args) => {
     // ausência que é só do parser.
     const callables = scan.callables.filter((name) => functionNames.includes(name));
     const rootIndexes = await readJson(join(root, 'firestore.indexes.json'));
-    const claims = await firstPartyClaims(root);
+    const claims = firstPartyClaims(root);
     const problems = claimProblems(claims, functionNames, rootIndexes.indexes);
     if (problems.length > 0) {
         throw new Error('An extension declares backend artifacts that do not add up, so the package would be wrong:\n'

package/package.json

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