@microteia/console 2.20.0 → 2.21.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,27 @@
 - 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.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.20.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/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.20.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.20.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.20.0",
+  "version": "2.21.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",