@microteia/console 2.7.0

package/lib/vendor/authoringGuide.js

@@ -0,0 +1,284 @@
+/**
+ * `AUTHORING.md` — o manual de quem escreve extensão, e o contraponto do `ARCHITECTURE.md`: aquele
+ * explica o kernel a quem o altera, este explica o CONTRATO a quem nunca vai vê-lo.
+ *
+ * Em inglês, e não por preferência: é superfície de produto, entregue a escritórios em qualquer lugar.
+ * A regra de idioma do repositório é exatamente essa — o produto fala inglês porque tem de poder falar
+ * qualquer idioma; o português é a nossa comunicação interna.
+ *
+ * Mora no Console (e não como arquivo `.md` solto) para que a versão do kernel e a lista de pontos de
+ * extensão sejam CARIMBADAS no texto: um manual que fala de um contrato diferente do instalado é pior
+ * que manual nenhum.
+ */
+const pointsTable = (points) => [
+    '| Point | API | Accepts | Many? |',
+    '|---|---|---|---|',
+    ...points.map((point) => `| \`${point.id}\` | ${point.apiVersion} | ${point.allowedImplKinds.length === 0 ? '_declaration only_' : point.allowedImplKinds.map((kind) => `\`${kind}\``).join(', ')} | ${point.multiple ? 'yes' : 'no'} |`),
+].join('\n');
+export const authoringGuide = (kernelVersion, points, hostModules) => `# Authoring Microteia extensions
+
+Kernel contract **${kernelVersion}**. Everything here describes the platform installed next to this
+directory, not a general idea of it.
+
+## 1. What an extension is
+
+A declaration. A single JSON document that says *what should exist* — screens, automations, actions,
+scripts, pages, translations, a theme — which the platform reads and installs. The platform has no
+knowledge of your extension: it only knows the points you contribute to.
+
+Two consequences you should take seriously:
+
+- **You never modify the platform.** There is no patch, no hook into internals, no override. If
+  something seems to require changing the kernel, you are looking at the wrong extension point.
+- **Uninstalling has to be clean.** Anything your extension declares can be withdrawn. That is why
+  option lists travel as *declarations* and not as data: the options belong to the organization, and
+  removing your extension must not delete them.
+
+## 2. The loop
+
+    npx microteia-plugin new com.example.hello    # scaffold
+    npx tsc --noEmit                              # types
+    npx microteia-plugin check hello/plugin.ts    # the gate
+    npx microteia-plugin build hello/plugin.ts    # writes the .json
+
+\`check\` is not an approximation of the platform's validation — it *is* the platform's validation, the
+same function, the same messages. If \`check\` passes, the package installs.
+
+Then import the \`.json\` on the **Extensions** screen.
+
+## 3. The package
+
+\`\`\`ts
+import type { AuthoredPlugin } from '@microteia/sdk';
+
+export default {
+  manifest: { id, version, kernel, name, publisher, contributes, /* dependencies, backend, ... */ },
+  summary: 'One line, shown in the Extensions list.',
+  workflows: [],       // required, may be empty
+  screens: [],         // entities, with their fields
+  screenPatches: [],   // fields added to a screen that already exists
+  lookups: [], tagLists: [],
+  actions: [], scripts: [],
+  views: [],           // pages delivered as code
+  startup: '',         // code that runs once when the extension loads
+  migrations: [],      // converting data an earlier version of YOURS wrote
+  overview: {},        // a rich description, in Widget DSL
+} satisfies AuthoredPlugin;
+\`\`\`
+
+Every field except \`manifest\`, \`summary\` and \`workflows\` is optional, and a package may be any
+subset — a single automation is a legitimate extension.
+
+**Two types, one letter apart, and it matters.** \`AuthoredPlugin\` is what you write — it lets a view
+point at a file with \`sourceFile\`. \`MarketplacePlugin\` is what the platform installs, where every
+view carries its \`source\` inline. The compiler turns the first into the second. Write against
+\`AuthoredPlugin\`; reach for \`MarketplacePlugin\` only when you are reading a built \`.json\` back.
+
+### Identity and versions
+
+\`manifest.id\` is reverse-DNS and permanent: it is how an update recognises the thing it updates. Use
+a domain you control. \`manifest.version\` is semver. \`manifest.kernel\` is the range of platform
+contracts you work against — \`^${kernelVersion}\` for what is installed here.
+
+Every change to an extension raises \`manifest.version\`, and records itself as one entry at the top of
+that extension's \`VERSIONS.md\` — the file \`create\` generates next to \`plugin.ts\`. The entry is
+written for whoever *uses* the extension: what they will notice, in one plain sentence, never the file
+or the field you touched. An extension changed without a new version is an extension that never reaches
+the organizations that already have it: the version is the whole of how an update is recognised.
+
+### References between your own artifacts
+
+Inside the package, artifacts point at each other by \`templateId\` (automations, actions, scripts) or
+\`key\` (screens), never by real id — the real ids are generated at install time and differ per
+organization. \`check\` refuses a reference that leads nowhere.
+
+To point at something *another* extension installs, declare it:
+
+\`\`\`ts
+dependencies: { 'com.example.projects': { version: '^2.0.0', collections: ['projects'] } }
+\`\`\`
+
+## 4. Extension points
+
+${pointsTable(points)}
+
+The \`Accepts\` column is the important one. Four kinds of implementation exist:
+
+| Kind | What it is | Who may use it |
+|---|---|---|
+| \`widget\` | a declarative tree the platform renders (Widget DSL) | anyone |
+| \`workflow\` | one of the automations in your package | anyone |
+| \`script\` | code in the server-side sandbox | anyone |
+| \`code\` | a React component, delivered as source | anyone — **but see §6** |
+
+Prefer \`widget\` when it is enough. A declarative page needs no review, cannot break, and survives
+platform upgrades without you touching it.
+
+## 5. Text — the rule that has no exception
+
+Every label a person reads is a **reference**, resolved at render:
+
+\`\`\`ts
+const label = (key: string) => \\\`@com.example.hello/\\\${key}\\\`;
+
+fields: [{ key: 'title', label: label('field.title'), type: 'text', order: 0 }]
+\`\`\`
+
+and the words themselves are a contribution:
+
+\`\`\`ts
+import { messageBundleContribution } from '@microteia/sdk';
+
+contributes: [
+  messageBundleContribution({ locale: 'en', namespace: 'com.example.hello', messages: EN }),
+  messageBundleContribution({ locale: 'pt-BR', namespace: 'com.example.hello', messages: PT_BR }),
+]
+\`\`\`
+
+Ship \`en\` always — it is the source language, and what someone sees when no translation for their
+locale is installed. **The platform does not translate your vocabulary.** "Document type" is the
+platform's concept; *Power of attorney* and *Petition* are yours, and only you can answer for them.
+
+A key with no translation renders as the key itself. Ugly, diagnosable, and never a blank screen.
+
+What the organization *typed* — a screen they named, a list option they added — is their data. It
+passes through untranslated, always.
+
+## 6. Code trust - why a human has to say yes
+
+A \`view\` travels as **source**. The browser compiles it and evaluates it against a fixed allowlist of
+modules:
+
+${hostModules.map((name) => `- \`${name}\``).join('\n')}
+
+Any other import throws. This is an import allowlist, not a sandbox: the code runs in the page, so it
+can reach \`fetch\` and the DOM like any script. The real containment is **provenance**.
+
+So: a package carrying \`views\` or \`startup\` installs **inert**. An administrator of the organization
+opens the source, reads it, and trusts it. The trust is bound to that exact code by content hash —
+change one character and it must be trusted again. Nothing you can put in the package changes this,
+and you should not design as though it might.
+
+Author views as real files:
+
+\`\`\`ts
+views: [{ key: 'summary', title: label('page.summary'), icon: 'chart', sourceFile: './views/Summary.view.tsx' }]
+\`\`\`
+
+\`sourceFile\` is an authoring field: the compiler replaces it with the file's contents. Keeping the
+code in a real \`.tsx\` is what lets \`tsc\` and your editor check the part of the extension most likely
+to be wrong.
+
+A view does not have to be one file. \`sourceFile\` also takes a list, merged in the order given:
+
+\`\`\`ts
+views: [{
+  key: 'summary',
+  title: label('page.summary'),
+  icon: 'chart',
+  sourceFile: ['./views/Summary.view.tsx', './views/Summary.viewmodel.tsx', './views/Summary.styles.tsx'],
+}]
+\`\`\`
+
+The package still carries one source per view — the runtime evaluates one module per view, and its
+\`require\` resolves nothing but the curated API. The list is an authoring convenience, and it changes
+three things you have to know:
+
+- **Import across the listed files normally.** The relative import is what makes \`tsc\` and your editor
+  connect them; the compiler erases it, because after the merge the names are already in scope. A
+  relative import pointing outside the list is refused at build time — the runtime could never resolve it.
+- **The merged module has one scope.** A top-level name declared in two of the files collides, and the
+  build says which name and which files. Importing the same thing from the same module in several files
+  is not a collision: those imports fold into one.
+- **Exactly one of the files exports \`default\`** — it is the view's component.
+
+\`startupFile\` takes a list for the same reason, and so do \`source\` and \`startup\` when the code
+reaches the package as text rather than as a path (a \`?raw\` import). There the merge cannot check a
+path, so it checks names: every name a relative import brings has to be declared by one of the merged
+sources, which is what catches merging the view and forgetting its view model.
+
+\`startup\` receives a \`host\` and may return a teardown function:
+
+\`\`\`ts
+export default function startup(host: ExtensionHost) {
+  host.commands.register({ /* ... */ });
+  return () => { /* undone when the extension is disabled */ };
+}
+\`\`\`
+
+## 7. Data your extension owns
+
+A \`screen\` declares an entity: a collection, its fields, its title. The platform draws the list, the
+detail, the form, the filters and the search. You write no UI for any of it.
+
+- **Fields the organization adds** to your screen are theirs. An update of your extension preserves them.
+- **Option lists** (\`lookups\`) travel as a declaration plus optional *seed* options. Seeds are written
+  only when the collection is empty; after that the options are the organization's, and neither an
+  update nor uninstalling touches them.
+- **\`screenPatches\`** add fields to a screen that already exists — someone else's, or the platform's.
+  They are added, never substituted, and uninstalling removes only yours.
+
+### Changing the shape of data you already wrote
+
+That needs a \`migration\`: code that runs once per organization, in the server sandbox, converting
+what an earlier version of *your* extension wrote. Never hard-code a collection name — read it from
+\`input.collections\`, because the name can differ. Write it to be safely re-runnable: it may resume.
+
+## 8. When your extension needs the server
+
+\`manifest.backend\` declares what the organization's Firebase project must provide — Cloud Functions,
+composite indexes, configuration parameters, manual prerequisites. The extension stays **pending**,
+and does not load, until an administrator runs \`microteia provision\`. Failing closed is deliberate: a
+menu whose backend is missing produces the most expensive kind of defect, where the app opens and
+every call fails looking like something else entirely.
+
+### You can write those functions yourself
+
+Put them in \`<folder>/functions/\`, read through its \`index.ts\`, and name each one in
+\`manifest.backend.functions\`. Then they behave exactly like the platform's own: deployed only where
+the extension is installed, removed by \`microteia provision --prune\` when nothing needs them.
+
+    npx microteia-plugin create function --plugin <folder>
+
+| What it needs | Where you declare it |
+|---|---|
+| an npm package the platform does not carry | \`dependencies\` in \`<folder>/functions/package.json\` |
+| a credential or setting | \`defineString('NAME')\`, and \`'NAME'\` in \`manifest.backend.parameters\` |
+| something a person must do by hand first | \`manifest.backend.prerequisites\` |
+
+Two rules follow from how a Firebase project works, and both are refusals rather than warnings:
+
+- **A \`defineString\` with no value refuses the deploy of *every* function in the project**, not just
+  yours — \`firebase-functions\` validates parameters globally. The Console lists every one it finds in
+  \`.env.<projectId>\`, empty, so filling it in is the only step left.
+- **One installation, one \`node_modules\`.** Two extensions asking for different ranges of the same
+  package is refused, because nothing decides between them. A range the platform already pins is kept:
+  the runtime is the platform's choice, and one extension may not move it for the others.
+
+A function shared by several extensions goes in \`../functions/\` instead, next to \`microteia.yaml\`.
+Nobody owns it, so nothing can claim it, and it is deployed with every \`microteia deploy\`.
+
+## 9. Size
+
+| | |
+|---|---|
+| Warning | 400 KiB |
+| Refused | 800 KiB |
+
+A package is stored as a single document. If you are near the limit, the usual cause is code that
+should be several extensions, or a seed list that should be data.
+
+## 10. Testing
+
+\`validatePluginPackage\` is exported from \`@microteia/sdk\` — the same function \`check\` calls. Keeping
+it in a test means a broken package fails in a second, on your machine:
+
+\`\`\`ts
+import { validatePluginPackage } from '@microteia/sdk';
+import plugin from './plugin';
+
+it('installs cleanly', () => { expect(validatePluginPackage(plugin)).toEqual([]); });
+\`\`\`
+
+Read \`examples/\` for first-party extensions that exercise every mechanism described above.
+`;

package/lib/vendor/bundleAudit.d.ts

@@ -0,0 +1,19 @@
+export interface BundleLeak {
+    file: string;
+    what: string;
+}
+/**
+ * Os valores dos `.env.*` da raiz. Comparar contra eles é melhor do que procurar um padrão: cobre
+ * qualquer ambiente que exista na máquina de quem empacota, inclusive um criado depois disto.
+ */
+export declare const environmentSecrets: (root: string) => Promise<string[]>;
+export declare const findBundleLeaks: (bundleDir: string, secrets: string[]) => Promise<BundleLeak[]>;
+/**
+ * Os `.d.ts` de um diretório que ainda carregam comentário.
+ *
+ * Existe pelo mesmo motivo do resto deste arquivo: confere o ARTEFATO, não o procedimento. O
+ * `tsconfig.sdk.json` liga `removeComments`, mas uma flag num arquivo de configuração pode ser
+ * desligada sem que ninguém perceba — e o que vazaria é o JSDoc deste repositório, que é em português
+ * e narra decisões internas, para dentro do pacote de todo escritório que instalar o SDK.
+ */
+export declare const declarationsWithComments: (directory: string) => Promise<string[]>;

package/lib/vendor/bundleAudit.js

@@ -0,0 +1,95 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * O bundle distribuído não pode carregar projeto Firebase nenhum.
+ *
+ * O risco não é teórico: até a versão 7.46 o Vite inlinava `VITE_*` em tempo de build, e um pacote
+ * montado com `TARGET=dev` levaria as credenciais de desenvolvimento embutidas. Como `config.ts` cai
+ * no valor inlinado quando ninguém carimba `firebase-config.js`, uma instalação mal carimbada
+ * conectaria em SILÊNCIO no Firebase de quem empacotou — escrevendo dados de cliente lá dentro.
+ *
+ * Por isso a verificação não confia no procedimento (`pack` compila com `TARGET=dist`, e `.env.dist`
+ * não existe): ela confere o artefato pronto.
+ */
+const TEXT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.html', '.css', '.json', '.map', '.txt'];
+/** Prefixo de toda chave de API web do Firebase — pega o caso em que não há `.env` local para comparar. */
+const FIREBASE_API_KEY_MARKER = 'AIzaSy';
+const isTextFile = (name) => TEXT_EXTENSIONS.some((extension) => name.endsWith(extension));
+const walk = async (directory, prefix = '') => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory())
+            files.push(...await walk(join(directory, entry.name), relative));
+        else if (isTextFile(entry.name))
+            files.push(relative);
+    }
+    return files;
+};
+/**
+ * Os valores dos `.env.*` da raiz. Comparar contra eles é melhor do que procurar um padrão: cobre
+ * qualquer ambiente que exista na máquina de quem empacota, inclusive um criado depois disto.
+ */
+export const environmentSecrets = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true });
+    const values = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.startsWith('.env.') || entry.name === '.env.example')
+            continue;
+        const content = await readFile(join(root, entry.name), 'utf8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '' || trimmed.startsWith('#'))
+                continue;
+            const equals = trimmed.indexOf('=');
+            if (equals === -1)
+                continue;
+            const value = trimmed.slice(equals + 1).trim().replace(/^["']|["']$/g, '');
+            // Valores curtos demais dão falso positivo contra código minificado.
+            if (value.length >= 8)
+                values.add(value);
+        }
+    }
+    return [...values];
+};
+export const findBundleLeaks = async (bundleDir, secrets) => {
+    const files = await walk(bundleDir);
+    const leaks = [];
+    for (const file of files) {
+        const content = await readFile(join(bundleDir, file), 'utf8');
+        for (const secret of secrets) {
+            if (content.includes(secret))
+                leaks.push({ file, what: `environment value ${secret.slice(0, 8)}…` });
+        }
+        if (content.includes(FIREBASE_API_KEY_MARKER)) {
+            leaks.push({ file, what: `a Firebase web API key (${FIREBASE_API_KEY_MARKER}…)` });
+        }
+    }
+    return leaks;
+};
+/**
+ * Os `.d.ts` de um diretório que ainda carregam comentário.
+ *
+ * Existe pelo mesmo motivo do resto deste arquivo: confere o ARTEFATO, não o procedimento. O
+ * `tsconfig.sdk.json` liga `removeComments`, mas uma flag num arquivo de configuração pode ser
+ * desligada sem que ninguém perceba — e o que vazaria é o JSDoc deste repositório, que é em português
+ * e narra decisões internas, para dentro do pacote de todo escritório que instalar o SDK.
+ */
+export const declarationsWithComments = async (directory) => {
+    const found = [];
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.name.endsWith('.d.ts') && (await readFile(path, 'utf8')).includes('/*')) {
+                found.push(path);
+            }
+        }
+    };
+    await walk(directory);
+    return found.sort();
+};

package/lib/vendor/changelogs.d.ts

@@ -0,0 +1,62 @@
+/**
+ * O histórico técnico dos DOIS artefatos que o escritório recebe — a plataforma e o Console.
+ *
+ * Cada um carrega o seu, e essa é a decisão inteira. O `KERNEL-VERSIONS.md` viaja dentro do pacote; o
+ * `CONSOLE-VERSIONS.md` viaja com o binário do Console. Enquanto os dois textos saem do artefato que
+ * eles descrevem, nenhum dos dois pode falar de uma versão que não está ali — que é exatamente o que
+ * acontecia com os guias de `extensions/` enquanto eles moravam no Console.
+ *
+ * Os dois são ESCRITOS EM INGLÊS, ao contrário do `VERSIONS.md` da raiz do repositório. A regra é a de
+ * sempre: o que é entregue a um escritório que pode estar em qualquer lugar é superfície de produto e
+ * fala inglês; o que é comunicação nossa continua em português. O `VERSIONS.md` da raiz é para o
+ * usuário do escritório e não viaja no pacote; estes dois são o registro do que mudou no código, para
+ * quem mantém ou integra uma instalação.
+ *
+ * **NÃO ficam em `extensions/`.** Aquele diretório é opcional (pode nem existir, e pode ter sido criado
+ * com `--dir` em qualquer lugar), é escrito pelo SDK, e já tem um `VERSIONS.md` por extensão dentro
+ * dele — um segundo arquivo com o mesmo nome, um nível acima, significando outra coisa. Os dois moram
+ * na raiz da instalação, ao lado do `microteia.yaml`, que é onde o `--version` aponta.
+ */
+export declare const KERNEL_CHANGELOG = "KERNEL-VERSIONS.md";
+export declare const CONSOLE_CHANGELOG = "CONSOLE-VERSIONS.md";
+export declare const changelogVersions: (contents: string) => string[];
+/**
+ * O que impede o arquivo de ser confiável, na ordem em que atrapalha.
+ *
+ * A primeira é a que existe para doer: a versão que está sendo empacotada tem de ser a do TOPO. Sem
+ * isso o histórico é opcional na prática, e um histórico opcional para na primeira release apressada
+ * — que é justamente a que alguém vai querer ler depois.
+ */
+export declare const changelogProblems: (file: string, contents: string, version: string) => string[];
+/**
+ * Lê o histórico e RECUSA se ele não cobre a versão que está saindo. Usado pelo `pack` e pelo
+ * `pack-console`, que são os dois momentos em que ainda dá para escrever a entrada.
+ *
+ * A recusa é do artefato, não do procedimento — mesma postura do `bundleAudit` e da conferência de
+ * reivindicações de backend: o que sai daqui vai para escritórios, e um pacote cujo histórico não
+ * menciona a própria versão é um pacote que ninguém consegue datar depois.
+ */
+export declare const readChangelog: (directory: string, file: string, version: string) => Promise<string>;
+/**
+ * A entrada de UMA versão, para ser o corpo do release publicado.
+ *
+ * O texto do release não é escrito à mão em lugar nenhum: ele é o mesmo parágrafo que já foi conferido
+ * pelo `pack`, recortado daqui. Dois textos sobre a mesma versão divergem — e o que divergiria é
+ * justamente o que fica visível para quem procura o que mudou.
+ *
+ * Recorta do cabeçalho da versão até o próximo cabeçalho, e não até o fim: o que vem depois é o
+ * histórico anterior, e ele já está publicado nos releases dele.
+ */
+export declare const changelogEntry: (contents: string, version: string) => string;
+export interface ChangelogRefresh {
+    written: string[];
+    missing: string[];
+}
+/**
+ * Põe os dois históricos na raiz da instalação, SOBREPONDO — pela mesma razão que o `MICROTEIA.md` é
+ * sobreposto: eles prometem estar atuais, e um documento que promete isso não pode ser editável.
+ *
+ * A falta de um dos dois avisa e não derruba nada. O do kernel falta num pacote anterior a esta
+ * capacidade, e trocar de kernel não pode falhar por causa de um documento.
+ */
+export declare const refreshChangelogs: (root: string, install: string) => Promise<ChangelogRefresh>;

package/lib/vendor/changelogs.js

@@ -0,0 +1,131 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { consoleRoot } from '../shared/paths.js';
+import { compareVersions } from '../kernel/manifest.js';
+/**
+ * O histórico técnico dos DOIS artefatos que o escritório recebe — a plataforma e o Console.
+ *
+ * Cada um carrega o seu, e essa é a decisão inteira. O `KERNEL-VERSIONS.md` viaja dentro do pacote; o
+ * `CONSOLE-VERSIONS.md` viaja com o binário do Console. Enquanto os dois textos saem do artefato que
+ * eles descrevem, nenhum dos dois pode falar de uma versão que não está ali — que é exatamente o que
+ * acontecia com os guias de `extensions/` enquanto eles moravam no Console.
+ *
+ * Os dois são ESCRITOS EM INGLÊS, ao contrário do `VERSIONS.md` da raiz do repositório. A regra é a de
+ * sempre: o que é entregue a um escritório que pode estar em qualquer lugar é superfície de produto e
+ * fala inglês; o que é comunicação nossa continua em português. O `VERSIONS.md` da raiz é para o
+ * usuário do escritório e não viaja no pacote; estes dois são o registro do que mudou no código, para
+ * quem mantém ou integra uma instalação.
+ *
+ * **NÃO ficam em `extensions/`.** Aquele diretório é opcional (pode nem existir, e pode ter sido criado
+ * com `--dir` em qualquer lugar), é escrito pelo SDK, e já tem um `VERSIONS.md` por extensão dentro
+ * dele — um segundo arquivo com o mesmo nome, um nível acima, significando outra coisa. Os dois moram
+ * na raiz da instalação, ao lado do `microteia.yaml`, que é onde o `--version` aponta.
+ */
+export const KERNEL_CHANGELOG = 'KERNEL-VERSIONS.md';
+export const CONSOLE_CHANGELOG = 'CONSOLE-VERSIONS.md';
+/**
+ * O cabeçalho de uma entrada. É o MESMO formato dos outros históricos do produto — o `VERSIONS.md` da
+ * raiz e o de cada extensão que o `create` gera —, para que não existam duas convenções para a mesma
+ * coisa.
+ */
+const ENTRY = /^#### \[(\d+\.\d+\.\d+)\] — /gm;
+/**
+ * O comentário HTML do topo é o MOLDE da entrada nova, e ele mostra um cabeçalho de verdade — é o que faz
+ * alguém acertar o formato sem procurar. Por isso ele sai antes da contagem: senão o molde é lido como a
+ * entrada mais recente do arquivo, e o histórico inteiro parece fora de ordem.
+ */
+const withoutTemplates = (contents) => contents.replace(/<!--[\s\S]*?-->/g, '');
+export const changelogVersions = (contents) => [...withoutTemplates(contents).matchAll(ENTRY)].map((match) => match[1]);
+/**
+ * O que impede o arquivo de ser confiável, na ordem em que atrapalha.
+ *
+ * A primeira é a que existe para doer: a versão que está sendo empacotada tem de ser a do TOPO. Sem
+ * isso o histórico é opcional na prática, e um histórico opcional para na primeira release apressada
+ * — que é justamente a que alguém vai querer ler depois.
+ */
+export const changelogProblems = (file, contents, version) => {
+    const versions = changelogVersions(contents);
+    const problems = [];
+    if (versions.length === 0) {
+        problems.push(`${file} carries no entry at all. Expected one headed "#### [${version}] — <date>".`);
+        return problems;
+    }
+    if (versions[0] !== version) {
+        problems.push(versions.includes(version)
+            ? `${file} has an entry for ${version}, but ${versions[0]} is on top. The newest goes first.`
+            : `${file} has no entry for ${version}, which is the version being packaged. Add one on top.`);
+    }
+    for (let index = 1; index < versions.length; index += 1) {
+        const order = compareVersions(versions[index - 1], versions[index]);
+        if (order === 0)
+            problems.push(`${file} lists ${versions[index]} twice.`);
+        else if (order < 0) {
+            problems.push(`${file} lists ${versions[index - 1]} above ${versions[index]}, and the newest goes first.`);
+        }
+    }
+    return problems;
+};
+/**
+ * Lê o histórico e RECUSA se ele não cobre a versão que está saindo. Usado pelo `pack` e pelo
+ * `pack-console`, que são os dois momentos em que ainda dá para escrever a entrada.
+ *
+ * A recusa é do artefato, não do procedimento — mesma postura do `bundleAudit` e da conferência de
+ * reivindicações de backend: o que sai daqui vai para escritórios, e um pacote cujo histórico não
+ * menciona a própria versão é um pacote que ninguém consegue datar depois.
+ */
+export const readChangelog = async (directory, file, version) => {
+    const contents = await readFile(join(directory, file), 'utf8').catch(() => {
+        throw new Error(`${join(directory, file)} does not exist, and every packaged version needs its entry there.`);
+    });
+    const problems = changelogProblems(file, contents, version);
+    if (problems.length > 0) {
+        throw new Error(`The technical changelog does not cover this version:\n${problems.map((problem) => `  ${problem}`).join('\n')}`);
+    }
+    return contents;
+};
+/**
+ * A entrada de UMA versão, para ser o corpo do release publicado.
+ *
+ * O texto do release não é escrito à mão em lugar nenhum: ele é o mesmo parágrafo que já foi conferido
+ * pelo `pack`, recortado daqui. Dois textos sobre a mesma versão divergem — e o que divergiria é
+ * justamente o que fica visível para quem procura o que mudou.
+ *
+ * Recorta do cabeçalho da versão até o próximo cabeçalho, e não até o fim: o que vem depois é o
+ * histórico anterior, e ele já está publicado nos releases dele.
+ */
+export const changelogEntry = (contents, version) => {
+    const body = withoutTemplates(contents);
+    const headings = [...body.matchAll(ENTRY)];
+    const index = headings.findIndex((match) => match[1] === version);
+    if (index === -1) {
+        throw new Error(`The changelog has no entry for ${version}.`);
+    }
+    const start = headings[index].index;
+    const end = index + 1 < headings.length ? headings[index + 1].index : body.length;
+    return `${body.slice(start, end).trim()}\n`;
+};
+/**
+ * Põe os dois históricos na raiz da instalação, SOBREPONDO — pela mesma razão que o `MICROTEIA.md` é
+ * sobreposto: eles prometem estar atuais, e um documento que promete isso não pode ser editável.
+ *
+ * A falta de um dos dois avisa e não derruba nada. O do kernel falta num pacote anterior a esta
+ * capacidade, e trocar de kernel não pode falhar por causa de um documento.
+ */
+export const refreshChangelogs = async (root, install) => {
+    const sources = [
+        [join(install, KERNEL_CHANGELOG), KERNEL_CHANGELOG],
+        [join(consoleRoot, CONSOLE_CHANGELOG), CONSOLE_CHANGELOG],
+    ];
+    const written = [];
+    const missing = [];
+    for (const [from, name] of sources) {
+        const contents = await readFile(from, 'utf8').catch(() => null);
+        if (contents === null) {
+            missing.push(name);
+            continue;
+        }
+        await writeFile(join(root, name), contents);
+        written.push(name);
+    }
+    return { written, missing };
+};

package/lib/vendor/exampleSources.d.ts

@@ -0,0 +1,29 @@
+/**
+ * As extensões de primeira parte, empacotadas como FONTE — `plugin.ts` e as views em `.tsx` —, uma pasta
+ * por 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.
+ *
+ * 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.
+ */
+/** 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>;
+/**
+ * Reescreve os imports de um plugin para a forma que o escritório usa.
+ *
+ * Um especificador relativo que alcance `domain/` ou os construtores de contribuição é, do lado de fora,
+ * `@microteia/sdk`. As views passam a ser vizinhas do `plugin.ts` (`./views/X`), porque no exemplo cada
+ * extensão tem a sua pasta — aqui elas moram num diretório comum, com um nível a mais.
+ */
+export declare const rewriteImports: (source: string) => string;
+/**
+ * Escreve `<target>/<plugin>/plugin.ts` e `<target>/<plugin>/views/*` para cada exemplo. Devolve os
+ * nomes escritos, que é o que o `pack` reporta.
+ */
+export declare const stageExamples: (repo: string, target: string) => Promise<string[]>;