@microteia/console 2.7.0

package/lib/vendor/exampleSources.js

@@ -0,0 +1,126 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * 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 const EXAMPLE_SOURCES = {
+    brasil: 'brasil.ts',
+    calendar: 'calendar.ts',
+    dashboard: 'dashboard.ts',
+    'locale-pt-br': 'localePtBr',
+    news: 'news.ts',
+};
+/**
+ * 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 const rewriteImports = (source) => source.replace(/from '(\.[^']*)'/g, (match, specifier) => {
+    if (/(^|\/)contributionBuilders$/.test(specifier) || specifier.includes('domain/')) {
+        return "from '@microteia/sdk'";
+    }
+    // `./views/<plugin>/Nome.tsx?raw` -> `./views/Nome.tsx?raw`
+    const view = /^\.\/views\/[^/]+\/(.+)$/.exec(specifier);
+    return view === null ? match : `from './views/${view[1]}'`;
+});
+const HEADER = (id) => `// Example: a Microteia first-party extension, as SOURCE.
+//
+// This is the same code that produces ${id}.json — the artifact the platform installs. Build it with:
+//
+//     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'.
+
+`;
+/**
+ * Os módulos VIZINHOS que o plugin importa — hoje, os catálogos de mensagem (`./newsMessages`,
+ * `./newsMessagesPtBr`). Um exemplo tem de viajar com o que ele importa, ou o `plugin.ts` staged não
+ * compila; enumerar os arquivos à mão numa lista aqui seria a mesma dívida que a lista de views era.
+ *
+ * A busca é transitiva porque um catálogo importa o outro (o de tradução lê o namespace do de origem),
+ * e é limitada ao diretório do marketplace: o que alcança `domain/` já virou `@microteia/sdk`.
+ */
+const siblingModules = async (marketplace, entry) => {
+    const collected = new Map();
+    const pending = [entry];
+    while (pending.length > 0) {
+        const name = pending.shift();
+        const source = await readFile(join(marketplace, name), 'utf8');
+        for (const match of source.matchAll(/from '\.\/([A-Za-z][\w.-]*)'/g)) {
+            const file = `${match[1]}.ts`;
+            if (collected.has(file))
+                continue;
+            try {
+                collected.set(file, rewriteImports(await readFile(join(marketplace, file), 'utf8')));
+            }
+            catch {
+                continue;
+            }
+            pending.push(file);
+        }
+    }
+    return collected;
+};
+const viewFiles = async (viewsDir) => {
+    try {
+        return (await readdir(viewsDir)).filter((name) => name.endsWith('.tsx') || name.endsWith('.ts'));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Escreve `<target>/<plugin>/plugin.ts` e `<target>/<plugin>/views/*` para cada exemplo. Devolve os
+ * nomes escritos, que é o que o `pack` reporta.
+ */
+export const stageExamples = async (repo, target) => {
+    const marketplace = join(repo, 'src/plugins/marketplace');
+    const written = [];
+    for (const [id, origin] of Object.entries(EXAMPLE_SOURCES)) {
+        const directory = join(target, id);
+        await mkdir(directory, { recursive: true });
+        if (origin.endsWith('.ts')) {
+            const source = await readFile(join(marketplace, origin), 'utf8');
+            await writeFile(join(directory, 'plugin.ts'), HEADER(id) + rewriteImports(source));
+            for (const [name, content] of await siblingModules(marketplace, origin)) {
+                await writeFile(join(directory, name), content);
+            }
+            const plugin = origin.replace(/\.ts$/, '');
+            const views = join(marketplace, 'views', plugin);
+            const files = await viewFiles(views);
+            if (files.length > 0)
+                await mkdir(join(directory, 'views'), { recursive: true });
+            for (const name of files) {
+                await writeFile(join(directory, 'views', name), await readFile(join(views, name), 'utf8'));
+            }
+        }
+        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))) {
+                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);
+            }
+        }
+        written.push(id);
+    }
+    return written.sort();
+};

package/lib/vendor/installationDocs.d.ts

@@ -0,0 +1,35 @@
+import type { KernelManifest } from '../kernel/manifest.js';
+/**
+ * Os dois documentos que ficam ao lado do `microteia.yaml`.
+ *
+ * Eram um `README.md` DENTRO do pacote, em `.microteia/install/`. Estava no lugar errado por duas razões:
+ * ninguém abre um diretório que se anuncia como descartável para ler documentação, e o que ele explicava
+ * — onde escrever function, onde ficam as configurações — apontava para caminhos de dentro dele mesmo,
+ * que é justamente o que não se deve editar.
+ *
+ * A divisão entre os dois é sobre QUEM ESCREVE:
+ *
+ * - `README.md` é do escritório. Nasce se não existir e nunca é reescrito — ele vai renomear coisas,
+ *   acrescentar o contexto do negócio dele, apagar o que não usa. Por isso só contém o que não muda.
+ * - `MICROTEIA.md` é nosso. É SOBREPOSTO a cada `unpack`, e é onde vai o detalhe que acompanha a versão:
+ *   a lista de comandos, os números do pacote, os caminhos. Um documento que promete estar atualizado
+ *   não pode ser editável, e um documento que a pessoa edita não pode prometer isso.
+ *
+ * Ao lado deles ficam os dois históricos técnicos, que seguem a política do `MICROTEIA.md` e moram em
+ * `changelogs.ts` — cada um viaja no artefato que descreve, e não neste módulo.
+ */
+export declare const INSTALLATION_README = "README.md";
+export declare const INSTALLATION_GUIDE = "MICROTEIA.md";
+/**
+ * O README do escritório. Escrito UMA vez, e daí em diante é dele.
+ *
+ * Deliberadamente sem número de versão, sem contagem de function e sem nada que envelheça: o que
+ * envelhece vive no `MICROTEIA.md`, que é reescrito. Um README com um dado velho ensina a desconfiar do
+ * arquivo inteiro.
+ */
+export declare const installationReadme: (officeName: string) => string;
+/**
+ * O documento técnico. SOBREPOSTO a cada `unpack`, e por isso é onde o detalhe que acompanha a versão
+ * pode viver — carimbado com os números do pacote que está instalado, não com uma cópia deles.
+ */
+export declare const installationGuide: (officeName: string, manifest: KernelManifest, examples: string[]) => string;

package/lib/vendor/installationDocs.js

@@ -0,0 +1,243 @@
+/**
+ * Os dois documentos que ficam ao lado do `microteia.yaml`.
+ *
+ * Eram um `README.md` DENTRO do pacote, em `.microteia/install/`. Estava no lugar errado por duas razões:
+ * ninguém abre um diretório que se anuncia como descartável para ler documentação, e o que ele explicava
+ * — onde escrever function, onde ficam as configurações — apontava para caminhos de dentro dele mesmo,
+ * que é justamente o que não se deve editar.
+ *
+ * A divisão entre os dois é sobre QUEM ESCREVE:
+ *
+ * - `README.md` é do escritório. Nasce se não existir e nunca é reescrito — ele vai renomear coisas,
+ *   acrescentar o contexto do negócio dele, apagar o que não usa. Por isso só contém o que não muda.
+ * - `MICROTEIA.md` é nosso. É SOBREPOSTO a cada `unpack`, e é onde vai o detalhe que acompanha a versão:
+ *   a lista de comandos, os números do pacote, os caminhos. Um documento que promete estar atualizado
+ *   não pode ser editável, e um documento que a pessoa edita não pode prometer isso.
+ *
+ * Ao lado deles ficam os dois históricos técnicos, que seguem a política do `MICROTEIA.md` e moram em
+ * `changelogs.ts` — cada um viaja no artefato que descreve, e não neste módulo.
+ */
+export const INSTALLATION_README = 'README.md';
+export const INSTALLATION_GUIDE = 'MICROTEIA.md';
+/**
+ * O README do escritório. Escrito UMA vez, e daí em diante é dele.
+ *
+ * Deliberadamente sem número de versão, sem contagem de function e sem nada que envelheça: o que
+ * envelhece vive no `MICROTEIA.md`, que é reescrito. Um README com um dado velho ensina a desconfiar do
+ * arquivo inteiro.
+ */
+export const installationReadme = (officeName) => `# ${officeName}
+
+This directory is a **Microteia** installation: a multi-tenant business platform where the applications
+are built by *declaration* — screens, automations, actions and pages arrive as extensions, and the
+platform itself is never modified.
+
+It is yours. Rename it, describe your business in it, delete what you do not use. Nothing rewrites this
+file. The reference that has to stay current lives in **[MICROTEIA.md](./MICROTEIA.md)**, which is
+replaced on every \`microteia unpack\` — read that one for commands, paths and version detail. Beside it,
+**[KERNEL-VERSIONS.md](./KERNEL-VERSIONS.md)** and **[CONSOLE-VERSIONS.md](./CONSOLE-VERSIONS.md)** say
+what changed in each version of the platform and of the Console.
+
+## The shape of this directory
+
+    microteia.yaml         this installation: name, Firebase project, region, kernel version
+    .env.<projectId>       your backend settings. Credentials — gitignored
+    KERNEL-VERSIONS.md     what changed in each version of the platform
+    CONSOLE-VERSIONS.md    what changed in each version of the Console that installs it
+    extensions/            the extensions you write
+    functions/             Cloud Functions shared by more than one extension
+    .microteia/            the unpacked platform. DISPOSABLE — nothing of yours lives here
+
+The line that explains the rest: **nothing you write lives in \`.microteia/\`.** That directory is
+replaced whole on every upgrade. Everything of yours sits beside this file.
+
+## Day to day
+
+    microteia unpack --version latest   # take the newest published platform version
+    microteia deploy                    # publish it — or --only hosting, --only functions
+    microteia provision                 # apply what installed extensions need
+
+\`unpack --version\` reads the published catalog, downloads the version and checks its sha256 before
+touching what is installed here. On a machine that cannot reach the catalog, name a file instead:
+\`microteia unpack --kernel <package>.tgz\`. And \`microteia --version\` says when a newer one is out.
+
+## Building your own extensions
+
+An extension is a declaration the platform installs — a screen with its fields, an automation, a page.
+You write it in TypeScript and a compiler produces the \`.json\` that gets installed:
+
+    cd extensions
+    npx microteia-plugin create        # guided: asks what the extension should carry
+    npx microteia-plugin check <folder>/plugin.ts
+    npx microteia-plugin build <folder>/plugin.ts
+
+\`extensions/examples/\` holds every extension that ships with Microteia, in source form — the best
+reference there is. \`extensions/AUTHORING.md\` is the contract: extension points, the API a page may
+use, translation rules, size limits.
+
+## Working with an AI assistant
+
+\`extensions/\` registers an MCP server (\`.mcp.json\`), so an assistant in your editor can ask **this**
+installation what it offers — the extension points it has, what a page may import, and whether what it
+just wrote would be accepted — instead of guessing from documentation. \`extensions/AGENTS.md\` holds the
+rules it should follow.
+
+The point of that is not novelty: it is that the assistant's answer can be *checked* before anything is
+installed, by the same validation the platform runs.
+`;
+const commandRows = () => [
+    '| Command | What it does |',
+    '|---|---|',
+    '| `microteia unpack --version <latest\\|x.y.z>` | Downloads a platform version, verifies it, and puts it in place. Touches no Firebase — safe any time |',
+    '| `microteia unpack --kernel <pkg>.tgz` | The same, from a file you already have — for a machine with no access to the catalog |',
+    '| `microteia deploy [--only …] [--prune]` | Publishes what is in place: `rules`, `indexes`, `functions`, `hosting`. `--prune` also deletes functions left behind in a region this version no longer uses |',
+    '| `microteia provision [--prune]` | 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 |',
+].join('\n');
+/**
+ * O documento técnico. SOBREPOSTO a cada `unpack`, e por isso é onde o detalhe que acompanha a versão
+ * pode viver — carimbado com os números do pacote que está instalado, não com uma cópia deles.
+ */
+export const installationGuide = (officeName, manifest, examples) => {
+    const baseline = (manifest.baselineFunctions ?? manifest.functions).length;
+    const claimed = manifest.functions.length - baseline;
+    return `# Microteia — installation reference
+
+> Generated by \`microteia unpack\`. **Replaced on every unpack** — do not edit it; put your own notes in
+> [README.md](./README.md), which is never rewritten.
+
+| | |
+|---|---|
+| Installation | ${officeName} |
+| Platform version | ${manifest.version} |
+| Extension contract | ${manifest.kernelVersion} |
+| Console required | ${manifest.minimumCliVersion} or newer |
+| Functions region | ${manifest.requires.functionsRegion} |
+| Cloud Functions | ${baseline} baseline, ${claimed} claimed by extensions |
+${manifest.sdk === undefined ? '' : `| Authoring SDK | ${manifest.sdk.version} |\n`}
+## 1. What lives where, and why
+
+    microteia.yaml              the installation record. Written by the commands; readable by you
+    .env.<projectId>            YOUR backend settings — credentials
+    .gitignore                  covers the two above
+    README.md                   yours, never rewritten
+    MICROTEIA.md                this file, replaced on every unpack
+    KERNEL-VERSIONS.md          the platform's technical history, replaced on every unpack
+    CONSOLE-VERSIONS.md         the Console's own, replaced on every unpack
+    extensions/                 the extensions you write
+      <plugin>/plugin.ts        the source of one extension
+      <plugin>/views/*.tsx      its pages, as real type-checked files
+      <plugin>/functions/       its own Cloud Functions
+      <plugin>/<id>.json        the built artifact — generated, do not hand-edit
+      examples/                 every first-party extension, in source form
+      AUTHORING.md              the authoring contract
+    functions/                  Cloud Functions shared by more than one extension
+    .microteia/                 DISPOSABLE
+      install/                  the unpacked platform. Replaced whole on every unpack
+      firebase-config.json      resolved from your Firebase project by \`connect\`
+
+**Nothing you write belongs in \`.microteia/\`.** \`unpack\` deletes that directory and replaces it; only
+\`functions/node_modules\` survives, and only because it is a cache. This is not a convention to respect —
+it is what makes an upgrade trustworthy, and the reason your files are elsewhere.
+
+## 2. Commands
+
+${commandRows()}
+
+\`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.
+
+Between the two, \`microteia.yaml\` says both: \`kernel.version\` is what is in place, \`kernel.deployed\`
+is what the project runs. \`microteia --version\` prints them next to the Console's own. What changed between
+two versions is in \`KERNEL-VERSIONS.md\` and \`CONSOLE-VERSIONS.md\`. Each is written by the artifact it
+describes — the first travels inside the package, the second with the Console — which is what keeps
+either from describing a version that is not installed here. Both are replaced on every unpack, so put
+nothing of yours in them.
+
+\`unpack\` replaces \`.microteia/install/\` whole, and a package carries only the platform's own composite
+indexes — an index an extension asks for is not in it, so that it does not travel to installations that
+never install that extension. So \`unpack\` puts back what this installation had already declared, from
+\`backend.indexes\` in \`microteia.yaml\`. Without that, publishing indexes after an upgrade would find
+indexes in the project that the file no longer declares, and **offer to delete them** — for extensions
+that are merely turned off, and whose indexes are the reason their screens are fast.
+
+An index of an extension you removed stays declared and is reported on every \`provision\`. It costs only
+writes on the collection it covers. \`microteia provision --prune\` lets it go: it drops out of this
+installation, and the next \`microteia deploy --only indexes\` offers to delete it from the project —
+deliberately, because you asked.
+
+## 3. Backend settings
+
+They live in \`.env.<projectId>\`, next to \`microteia.yaml\`. \`unpack\` creates the file and adds any
+setting a new version introduces, **never overwriting what you filled in**.
+
+After changing a value, run \`microteia provision\`. The value is stamped into each Cloud Function at
+*its* deploy, so a function already running keeps the previous one until it is deployed again; provision
+notices the change (by a salted digest in \`microteia.yaml\`) and requeues exactly the functions that
+carry that setting.
+
+An empty line means "not configured". A feature that needs it stays off rather than failing halfway.
+
+## 4. Your own Cloud Functions
+
+Two places, answering two different questions:
+
+| Where | When |
+|---|---|
+| \`extensions/<plugin>/functions/\` | the function belongs to that extension |
+| \`functions/\` | the function is shared by more than one |
+
+Each directory is read through its \`index.ts\` — export from there what should be deployed.
+\`microteia deploy\` gathers them into the package, generates the entry point, and refuses the deploy if
+two of them export the same name, or if one collides with a platform function. That refusal matters: the
+entry point spreads yours *after* the platform's, so a repeated name would replace a platform trigger
+silently, and a trigger that was replaced does not fail — it simply stops happening.
+
+A function that belongs to an extension should also be declared in its
+\`manifest.backend.functions\`. That is what makes the installation deploy it only where the extension is
+installed, instead of everywhere.
+
+Functions are pinned to **${manifest.requires.functionsRegion}**. One in another region receives no
+Firestore trigger from this project, and the deploy reports nothing.
+
+## 5. Writing extensions
+
+    cd extensions
+    npx microteia-plugin create                 # guided
+    npx microteia-plugin create function        # adds a Cloud Function to an existing extension
+    npx tsc --noEmit                            # types
+    npx microteia-plugin check <folder>/plugin.ts
+    npx microteia-plugin build <folder>/plugin.ts
+
+\`check\` is not an approximation of the platform's validation — it *is* it, the same function and the
+same messages. If \`check\` passes, the package installs.
+
+**A package that carries code installs inert.** An administrator opens the source, reads it, and trusts
+it; the trust is bound to that exact code by hash. Changing one character requires trusting it again.
+
+### Examples included with this version
+
+${examples.length === 0 ? '_None in this package._' : examples.map((id) => `- \`extensions/examples/${id}/\``).join('\n')}
+
+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
+
+## 6. An AI assistant in this directory
+
+\`extensions/.mcp.json\` registers an MCP server that answers from **this** installation: the extension
+points it has, what a page may import, the authoring guide, and whether a package would be accepted.
+\`extensions/AGENTS.md\` (and \`CLAUDE.md\`, the same content) holds the rules.
+
+The validation tool is the part that matters — it closes the loop between what an assistant proposes and
+what the platform would do with it, before anything is installed.
+
+## 7. Manual prerequisites
+
+Things no command can do for you, in the Firebase or Google Cloud console:
+
+${manifest.manualPrerequisites.map((prerequisite) => `- **${prerequisite.title}**${prerequisite.optional ? ' _(optional)_' : ''}\n  ${prerequisite.detail}`).join('\n')}
+`;
+};

package/lib/vendor/pack.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../shared/args.js';
+export declare const pack: (args: ParsedArgs) => Promise<void>;