@microteia/console 2.7.0

package/lib/vendor/pack.js

@@ -0,0 +1,276 @@
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { flagValue, hasFlag } from '../shared/args.js';
+import { repoRoot } from '../shared/paths.js';
+import { run } from '../shared/run.js';
+import { blank, bullets, heading, info, step, success } from '../shared/ui.js';
+import { DEFAULT_FUNCTIONS_REGION, KERNEL_COMPONENTS, KERNEL_DISTRIBUTION_ID, MANUAL_PREREQUISITES, MINIMUM_CLI_VERSION, REQUIRED_NODE_VERSION, callableFunctionNames, declaredParametersIn, exportedFunctionNames, parseKernelVersion, } from '../kernel/manifest.js';
+import { digestOfFile } from '../shared/digest.js';
+import { kernelTarballName } from '../kernel/channel.js';
+import { baselineFunctionsOf, baselineIndexesOf, claimProblems, claimsFromTemplates, } from '../kernel/backendShape.js';
+import { declarationsWithComments, environmentSecrets, findBundleLeaks } from './bundleAudit.js';
+import { KERNEL_CHANGELOG, readChangelog } from './changelogs.js';
+import { assertInsideRepository } from './repository.js';
+import { SDK_TARBALL } from './pluginWorkspaceTemplates.js';
+import { stageExamples } from './exampleSources.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
+ * projeto embutido: o repositório não tem `.env` de raiz servindo de fallback, então nada é inlinado.
+ */
+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.
+ */
+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 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
+ * varredura é a árvore inteira de `functions/src`, uma vez, para os dois. Derivar daqui é o que faz
+ * um parâmetro novo (ou uma callable nova) aparecer sozinho no manifesto, em vez de depender de
+ * alguém lembrar de atualizar um template.
+ */
+const scanBackendSources = async (directory) => {
+    const parameters = new Map();
+    const callables = new Set();
+    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('.ts') && !entry.name.endsWith('.test.ts')) {
+                const source = await readFile(path, 'utf8');
+                for (const parameter of declaredParametersIn(source)) {
+                    const previous = parameters.get(parameter.name);
+                    // Declarado em dois lugares com defaults diferentes: vale o mais exigente.
+                    if (previous === undefined || parameter.required)
+                        parameters.set(parameter.name, parameter);
+                }
+                for (const name of callableFunctionNames(source))
+                    callables.add(name);
+            }
+        }
+    };
+    await walk(directory);
+    return {
+        parameters: [...parameters.values()].sort((left, right) => left.name.localeCompare(right.name)),
+        callables: [...callables].sort((left, right) => left.localeCompare(right)),
+    };
+};
+/**
+ * Põe o SDK de autoria no pacote: o compilado, os tipos da API curada, e as extensões de primeira
+ * parte como exemplo.
+ *
+ * O tarball vai com nome FIXO (`microteia-sdk.tgz`, sem versão) porque o `extensions/package.json` do
+ * escritório aponta para ele por caminho: com a versão no nome, todo upgrade exigiria editar aquele
+ * arquivo à mão, e quem esquecesse continuaria compilando contra o SDK antigo em silêncio.
+ *
+ * As três conferências do fim são do ARTEFATO, não do procedimento — mesma postura do `bundleAudit`:
+ * o que sai daqui é `.d.ts` da superfície curada, e um comentário esquecido nele levaria para todo
+ * escritório a narrativa interna de uma decisão nossa.
+ */
+const stageSdk = async (root, stageDir, version) => {
+    const sourceDir = join(root, 'sdk');
+    const targetDir = join(stageDir, 'sdk');
+    const manifest = await readJson(join(sourceDir, 'package.json'));
+    const kernelVersion = manifest.microteia?.kernelVersion;
+    if (manifest.version !== version || kernelVersion === undefined) {
+        throw new Error('sdk/package.json is stale — "npm run verify" should have rebuilt it.');
+    }
+    await mkdir(targetDir, { recursive: true });
+    await run('npm', ['pack', '--silent', '--pack-destination', targetDir], { cwd: sourceDir });
+    const packed = (await readdir(targetDir)).filter((file) => file.endsWith('.tgz'));
+    if (packed.length !== 1) {
+        throw new Error(`Expected exactly one SDK tarball, found ${packed.length}.`);
+    }
+    await rename(join(targetDir, packed[0]), join(targetDir, SDK_TARBALL));
+    await cp(join(sourceDir, 'types'), join(targetDir, 'types'), { recursive: true });
+    // O `.d.ts` da superfície curada sai SEM comentário: o JSDoc deste repositório é em português e
+    // narra decisões e incidentes internos. O que o autor lê é `types/` e o `AUTHORING.md`, escritos
+    // para ele — e por isso `types/` fica de fora desta conferência, de propósito.
+    const documented = await declarationsWithComments(join(sourceDir, 'lib'));
+    if (documented.length > 0) {
+        throw new Error('Declarations in the SDK carry comments, which would ship internal notes to every office:\n'
+            + documented.map((file) => `  ${relative(sourceDir, file)}`).join('\n')
+            + '\n"removeComments" must stay on in tsconfig.sdk.json.');
+    }
+    // As extensões de primeira parte como material de autoria, em FONTE e uma pasta por extensão. O
+    // `.json` é o artefato e não ensina como se chega nele; a fonte ensina, e já viajava de qualquer
+    // forma — o código das views está dentro do `.json`, em string. `exampleSources.test.ts` compila cada
+    // uma e exige o `.json` versionado byte a byte.
+    const examples = await stageExamples(root, join(targetDir, 'examples'));
+    info(`  ${examples.length} first-party extension(s) staged as source examples`);
+    return { version, kernelVersion, path: `sdk/${SDK_TARBALL}` };
+};
+export const pack = async (args) => {
+    await assertInsideRepository('pack');
+    const root = repoRoot;
+    const skipVerify = hasFlag(args, 'skip-verify');
+    const pkg = await readJson(join(root, 'package.json'));
+    const version = pkg.version;
+    /**
+     * O histórico técnico é conferido AQUI, antes de qualquer build. Uma entrada que falta é um minuto de
+     * conserto; descobri-la depois do `verify` e dos três builds custa dez, e é assim que a conferência
+     * passa a ser contornada com `--skip-verify`.
+     */
+    const changelog = await readChangelog(root, KERNEL_CHANGELOG, version);
+    const kernelVersion = parseKernelVersion(await readFile(join(root, 'src/domain/schema/plugin/kernelVersion.ts'), 'utf8'));
+    const functionNames = exportedFunctionNames(await readFile(join(root, 'functions/src/index.ts'), 'utf8'));
+    const scan = await scanBackendSources(join(root, 'functions/src'));
+    const backendParameters = scan.parameters;
+    // Uma callable que não está exportada no `index.ts` não é deployada, e verificá-la acusaria uma
+    // 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 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'
+            + problems.map((problem) => `  ${problem}`).join('\n'));
+    }
+    const baselineFunctions = baselineFunctionsOf(functionNames, claims);
+    const baselineIndexes = baselineIndexesOf(rootIndexes.indexes, claims);
+    const outputDir = flagValue(args, 'output') ?? join(root, 'distributions', 'kernel', version);
+    const stageDir = join(outputDir, 'package');
+    const tarball = join(outputDir, kernelTarballName(version));
+    heading(`Packaging Microteia kernel ${version} (contract ${kernelVersion})`);
+    const total = 7;
+    if (skipVerify) {
+        info('Quality gate skipped (--skip-verify).');
+    }
+    else {
+        step(1, total, 'Quality gate');
+        await run('npm', ['run', 'verify'], { cwd: root });
+    }
+    step(2, total, `Building the portable frontend (TARGET=${DISTRIBUTION_TARGET})`);
+    await run('npm', ['run', 'build'], { cwd: root, env: { TARGET: DISTRIBUTION_TARGET } });
+    step(3, total, 'Compiling the Cloud Functions');
+    await run('npm', ['run', 'build:functions'], { cwd: root });
+    // Depois do `verify`, que já compilou o SDK — mas o `--skip-verify` existe, e um pacote sem SDK
+    // seria descoberto só no `plugin-init` de um escritório.
+    step(4, total, 'Building the authoring SDK');
+    await run('npm', ['run', 'build:host-types'], { cwd: root });
+    await run('npm', ['run', 'build:sdk'], { cwd: root });
+    step(5, total, 'Checking that the bundle carries no Firebase project');
+    const leaks = await findBundleLeaks(join(root, 'dist'), await environmentSecrets(root));
+    if (leaks.length > 0) {
+        throw new Error('The built frontend contains Firebase credentials, so it is not distributable.\n'
+            + leaks.map((leak) => `  ${leak.file}: ${leak.what}`).join('\n')
+            + `\nThe distribution build must run with TARGET=${DISTRIBUTION_TARGET}, for which no env file exists.`);
+    }
+    success('no project baked into the bundle');
+    step(6, total, 'Assembling the distribution');
+    await rm(stageDir, { recursive: true, force: true });
+    await mkdir(stageDir, { recursive: true });
+    const repoFirebase = await readJson(join(root, 'firebase.json'));
+    if (repoFirebase.hosting === undefined)
+        throw new Error('firebase.json has no hosting section.');
+    const repoFunctions = await readJson(join(root, 'functions/package.json'));
+    // `.DS_Store` e afins vêm de `public/` e entram no `dist` pela cópia literal que o Vite faz. O
+    // hosting já os ignoraria no upload, mas eles não têm por que existir dentro do pacote.
+    await cp(join(root, 'dist'), join(stageDir, 'hosting'), {
+        recursive: true,
+        filter: (source) => !basename(source).startsWith('.'),
+    });
+    // Os `.js.map` ficam de fora: sem o `src/` que eles apontam são inúteis para quem instala, e
+    // publicá-los entregaria a árvore interna de módulos do kernel — o desenho, ainda que não o
+    // código. (`sourcesContent` não é emitido, então o TypeScript em si nunca esteve neles.)
+    await cp(join(root, 'functions/lib'), join(stageDir, 'functions/lib'), {
+        recursive: true,
+        filter: (source) => !source.endsWith('.map'),
+    });
+    await cp(join(root, 'functions/package-lock.json'), join(stageDir, 'functions/package-lock.json'));
+    // O `.env.example` NÃO viaja. Dentro de `install/functions/` ele era uma armadilha: convidava a
+    // preencher a configuração ali, num diretório que o deploy seguinte apaga por inteiro. O que a
+    // instalação recebe é o `.env.<projectId>` na RAIZ, escrito a partir do manifesto e já comentado —
+    // um modelo a menos é um lugar errado a menos.
+    for (const file of ['firestore.rules', 'storage.rules']) {
+        await cp(join(root, file), join(stageDir, file));
+    }
+    // O histórico do kernel viaja DENTRO do pacote, e é de lá que o `unpack` o copia para a raiz da
+    // instalação. Escrito do conteúdo já conferido, para não ler o arquivo duas vezes.
+    await writeFile(join(stageDir, KERNEL_CHANGELOG), changelog);
+    // O `firestore.indexes.json` do pacote é ESCRITO, não copiado: a raiz é o conjunto completo (é o que
+    // roda em `microteia-dev` e `curatino`), e o que uma extensão reivindica sai daqui para ser criado
+    // pelo `provision` quando ela for instalada. Os `fieldOverrides` são todos do kernel e vão inteiros.
+    await writeFile(join(stageDir, 'firestore.indexes.json'), `${JSON.stringify({ ...rootIndexes, indexes: baselineIndexes }, null, 2)}\n`);
+    await mkdir(join(stageDir, 'functions/custom/src'), { recursive: true });
+    await writeFile(join(stageDir, 'firebase.json'), packageFirebaseJson(repoFirebase.hosting));
+    await writeFile(join(stageDir, 'functions/package.json'), packageFunctionsPackageJson(repoFunctions, version));
+    await writeFile(join(stageDir, 'functions/index.js'), packageFunctionsIndexJs());
+    await writeFile(join(stageDir, 'functions/custom/tsconfig.json'), packageCustomTsconfig());
+    await writeFile(join(stageDir, 'functions/custom/src/index.ts'), packageCustomIndexTs());
+    const sdk = await stageSdk(root, stageDir, version);
+    const manifest = {
+        id: KERNEL_DISTRIBUTION_ID,
+        name: 'Microteia Kernel',
+        version,
+        kernelVersion,
+        minimumCliVersion: MINIMUM_CLI_VERSION,
+        packagedAt: new Date().toISOString(),
+        components: KERNEL_COMPONENTS,
+        requires: {
+            functionsRegion: DEFAULT_FUNCTIONS_REGION,
+            nodeVersion: REQUIRED_NODE_VERSION,
+        },
+        functions: functionNames,
+        baselineFunctions,
+        baselineIndexes,
+        callables,
+        backendParameters,
+        manualPrerequisites: MANUAL_PREREQUISITES,
+        sdk,
+    };
+    await writeFile(join(stageDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    step(7, total, 'Writing the tarball');
+    await run('tar', ['-czf', tarball, '-C', stageDir, '.'], { cwd: root });
+    await rm(stageDir, { recursive: true, force: true });
+    /**
+     * A segunda cópia do manifesto, FORA do tarball, para que a versão e os pré-requisitos possam ser
+     * lidos sem desempacotar nada — e agora também para que o que foi BAIXADO possa ser conferido.
+     *
+     * Ela deixou de ser o mesmo JSON da de dentro, e vem depois do `tar` por causa disso: o `sha256` é do
+     * arquivo que acabou de ser escrito, e a cópia de dentro dele não teria como carregá-lo. É a única
+     * diferença entre as duas, e está declarada no tipo.
+     */
+    const digest = await digestOfFile(tarball);
+    const published = {
+        ...manifest,
+        tarball: { name: basename(tarball), ...digest },
+    };
+    await writeFile(join(outputDir, 'manifest.json'), `${JSON.stringify(published, null, 2)}\n`);
+    blank();
+    info(`Kernel ${version} packaged.`);
+    bullets([
+        `tarball:  ${tarball}`,
+        `manifest: ${join(outputDir, 'manifest.json')}`,
+        `functions: ${functionNames.length} packaged, ${baselineFunctions.length} in the baseline`,
+        `callables: ${callables.length}`,
+        `claimed by extensions: ${functionNames.length - baselineFunctions.length} function(s), `
+            + `${rootIndexes.indexes.length - baselineIndexes.length} index(es), from ${claims.length} extension(s)`,
+        `backend parameters: ${backendParameters.length}`,
+        `authoring SDK: ${sdk.version} (kernel contract ${sdk.kernelVersion})`,
+        `size: ${(digest.bytes / 1_000_000).toFixed(1)} MB, sha256 ${digest.sha256.slice(0, 12)}…`,
+    ]);
+    blank();
+    info('Publish it with:');
+    bullets(['microteia publish --dry-run   (says what would go up)', 'microteia publish']);
+    blank();
+    info('Or install this file directly, without publishing:');
+    bullets([
+        'microteia init --name <office>',
+        'microteia connect --project <firebase-project-id>',
+        `microteia unpack --kernel ${tarball}`,
+        'microteia deploy',
+        'microteia plugin-init   (optional: author extensions in TypeScript)',
+    ]);
+    blank();
+};

package/lib/vendor/packConsole.d.ts

@@ -0,0 +1,13 @@
+import type { ParsedArgs } from '../shared/args.js';
+/**
+ * O Console pronto para rodar em outra pasta — ou em outra máquina — sem o repositório.
+ *
+ * O que ele monta é pequeno de propósito: o `lib/` compilado, um `package.json` e um README. Não há
+ * dependência de npm a instalar porque o Console usa só módulos nativos do Node; o que ele exige são
+ * BINÁRIOS (`firebase`, `npm`, `tar`, `gcloud`), e esses são da máquina, não do pacote.
+ *
+ * O `package.json` é a razão de este comando existir em vez de um `cp -R`: o compilado é ESM, e sem
+ * `type: module` o Node só o carrega por adivinhação de sintaxe — disponível a partir do 22.7 e
+ * ausente antes dele. Montar a pasta à mão significa esquecer disso e culpar a ferramenta.
+ */
+export declare const packConsole: (args: ParsedArgs) => Promise<void>;

package/lib/vendor/packConsole.js

@@ -0,0 +1,63 @@
+import { access, chmod, cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { flagValue } from '../shared/args.js';
+import { CLI_VERSION, consoleRoot, repoRoot } from '../shared/paths.js';
+import { blank, bullets, heading, info, step, success } from '../shared/ui.js';
+import { CONSOLE_CHANGELOG, readChangelog } from './changelogs.js';
+import { consolePackageJson, consoleReadme } from './packageTemplates.js';
+import { assertInsideRepository } from './repository.js';
+/**
+ * O Console pronto para rodar em outra pasta — ou em outra máquina — sem o repositório.
+ *
+ * O que ele monta é pequeno de propósito: o `lib/` compilado, um `package.json` e um README. Não há
+ * dependência de npm a instalar porque o Console usa só módulos nativos do Node; o que ele exige são
+ * BINÁRIOS (`firebase`, `npm`, `tar`, `gcloud`), e esses são da máquina, não do pacote.
+ *
+ * O `package.json` é a razão de este comando existir em vez de um `cp -R`: o compilado é ESM, e sem
+ * `type: module` o Node só o carrega por adivinhação de sintaxe — disponível a partir do 22.7 e
+ * ausente antes dele. Montar a pasta à mão significa esquecer disso e culpar a ferramenta.
+ */
+export const packConsole = async (args) => {
+    await assertInsideRepository('pack-console');
+    const compiled = join(repoRoot, 'cli', 'lib');
+    const outputDir = flagValue(args, 'output')
+        ?? join(repoRoot, 'distributions', 'console', CLI_VERSION);
+    heading(`Packaging Microteia Console ${CLI_VERSION}`);
+    const total = 3;
+    step(1, total, 'Checking the compiled Console');
+    try {
+        await access(join(compiled, 'index.js'));
+    }
+    catch {
+        throw new Error(`${compiled} has no compiled Console. Run "npm run build:cli" first `
+            + '(or use "npm run pack:console", which does it).');
+    }
+    success(`${compiled}/index.js`);
+    /**
+     * O histórico do Console viaja COM o Console, e não com o pacote do kernel: é o único jeito de ele não
+     * poder descrever uma versão que não está ali. A conferência vem antes de montar a pasta, porque uma
+     * entrada que falta se escreve em um minuto e nada mais depende dela.
+     */
+    step(2, total, 'Checking the changelog');
+    const changelog = await readChangelog(consoleRoot, CONSOLE_CHANGELOG, CLI_VERSION);
+    success(`${CONSOLE_CHANGELOG} covers ${CLI_VERSION}`);
+    step(3, total, 'Assembling the folder');
+    await rm(outputDir, { recursive: true, force: true });
+    await mkdir(outputDir, { recursive: true });
+    await cp(compiled, join(outputDir, 'lib'), { recursive: true });
+    await writeFile(join(outputDir, 'package.json'), consolePackageJson(CLI_VERSION));
+    await writeFile(join(outputDir, 'README.md'), consoleReadme(CLI_VERSION));
+    await writeFile(join(outputDir, CONSOLE_CHANGELOG), changelog);
+    // Executável com o shebang que o entrypoint já tem: é o que permite apontar um link para ele em
+    // qualquer diretório do PATH, sem npm e sem sudo. O `tsc` não carimba a permissão, e no repositório
+    // ela vem do `npm install` (que a aplica no alvo do `bin`) — o que não existe numa pasta copiada.
+    await chmod(join(outputDir, 'lib', 'index.js'), 0o755);
+    success(outputDir);
+    blank();
+    info('Publish it with:');
+    bullets(['microteia publish --console-only --dry-run', 'microteia publish --console-only']);
+    blank();
+    info('Or run this folder as it is, on any machine with Node 22 and the Firebase CLI:');
+    bullets([`node ${join(outputDir, 'lib', 'index.js')} --help`]);
+    blank();
+};

package/lib/vendor/packageTemplates.d.ts

@@ -0,0 +1,66 @@
+/**
+ * O que é GERADO dentro do pacote — o que difere de um workspace de deploy do repositório.
+ *
+ * O `firebase.json` do repositório não serve como está por duas razões: o `predeploy` dele compila o
+ * kernel (que no pacote já vem compilado, e cujo `src/` não viaja), e o hosting dele aponta para
+ * `dist`. Aqui o `predeploy` compila SÓ o que o escritório escreveu.
+ */
+export interface RepoFunctionsPackage {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    engines?: Record<string, string>;
+}
+export interface HostingConfig {
+    ignore: string[];
+    rewrites: unknown[];
+    headers: unknown[];
+}
+export declare const packageFirebaseJson: (hosting: HostingConfig) => string;
+/**
+ * As dependências são copiadas INTACTAS do `functions/package.json` do repositório, para que o
+ * `package-lock.json` que viaja junto continue válido. O que muda é só o entrypoint (passa a ser o
+ * `index.js` que soma kernel e custom) e o `build`, que agora compila apenas `custom/`.
+ */
+/**
+ * A `version` não é enfeite: sem ela o npm não consegue formar `nome@versão` e todo aviso dele sobre
+ * este pacote sai com `package: undefined`, o que faz parecer que o arquivo está corrompido.
+ *
+ * `engines.node` vem do repositório e descreve o RUNTIME das Cloud Functions — é por ele que o Firebase
+ * escolhe em qual Node a function roda. Ele não descreve a máquina de quem instala, e é por isso que o
+ * npm avisa `EBADENGINE` quando as duas versões diferem: o aviso é esperado e não impede nada. Trocar
+ * o valor por uma faixa (`>=22`) calaria o aviso e passaria a deixar a escolha do runtime ambígua para
+ * o Firebase — o preço errado pela linha de saída.
+ */
+export declare const packageFunctionsPackageJson: (source: RepoFunctionsPackage, version: string) => string;
+/**
+ * Entrypoint da instalação. O espalhamento mantém os nomes PLANOS (`onUserCreated`, e não
+ * `kernel-onUserCreated`), que é o que os deploys por nome e os gatilhos já existentes esperam.
+ */
+export declare const packageFunctionsIndexJs: () => string;
+/**
+ * O `exclude` é cinto de segurança, não redundância: o `gatherCustomFunctions` já não copia teste para
+ * cá, mas ele reconhece as duas convenções usuais (`*.test.ts`, `__tests__/`) e um arquivo fora delas
+ * chegaria. Aqui ele chega e não compila — o que é um upload maior, e não um deploy quebrado.
+ */
+export declare const packageCustomTsconfig: () => string;
+export declare const packageCustomIndexTs: () => string;
+export declare const CONSOLE_PACKAGE_NAME = "@microteia/console";
+/**
+ * O Console empacotado para rodar FORA do repositório — e agora publicável.
+ *
+ * O `type: module` não é detalhe: o compilado é ESM, e sem esta declaração o Node só o carrega por
+ * adivinhação de sintaxe — que existe a partir do 22.7 e falha em silêncio nas versões anteriores, com
+ * "Cannot use import statement outside a module". O `bin` é o que dá o comando `microteia` global.
+ *
+ * Ele deixou de ser `private`, e isso resolve um ovo-e-galinha: enquanto o Console também tinha de ser
+ * baixado de algum lugar, alguém precisava baixar o baixador — e o primeiro passo de quem instala era
+ * uma pasta recebida por e-mail e um `ln -s` escrito à mão. Publicado, o registry já dá URL versionada,
+ * impressão digital no lock, CDN e `npm outdated`, que era tudo o que o canal precisaria reimplementar.
+ *
+ * `files` é a lista exata, e o `CONSOLE-VERSIONS.md` está nela por um motivo que não é documentação: o
+ * `unpack` lê aquele arquivo AO LADO do binário que está rodando para pô-lo na raiz da instalação. Fora
+ * de `files`, ele não existe numa instalação global, e o comando passa a avisar que o Console não carrega
+ * histórico — na máquina do escritório, e só lá.
+ */
+export declare const consolePackageJson: (version: string) => string;
+export declare const consoleReadme: (version: string) => string;

package/lib/vendor/packageTemplates.js

@@ -0,0 +1,200 @@
+/**
+ * O que é GERADO dentro do pacote — o que difere de um workspace de deploy do repositório.
+ *
+ * O `firebase.json` do repositório não serve como está por duas razões: o `predeploy` dele compila o
+ * kernel (que no pacote já vem compilado, e cujo `src/` não viaja), e o hosting dele aponta para
+ * `dist`. Aqui o `predeploy` compila SÓ o que o escritório escreveu.
+ */
+export const packageFirebaseJson = (hosting) => JSON.stringify({
+    firestore: {
+        rules: 'firestore.rules',
+        indexes: 'firestore.indexes.json',
+    },
+    storage: {
+        rules: 'storage.rules',
+    },
+    functions: {
+        source: 'functions',
+        predeploy: ['npm --prefix "$RESOURCE_DIR" run build'],
+    },
+    hosting: {
+        public: 'hosting',
+        ignore: hosting.ignore,
+        rewrites: hosting.rewrites,
+        headers: hosting.headers,
+    },
+}, null, 2) + '\n';
+/**
+ * As dependências são copiadas INTACTAS do `functions/package.json` do repositório, para que o
+ * `package-lock.json` que viaja junto continue válido. O que muda é só o entrypoint (passa a ser o
+ * `index.js` que soma kernel e custom) e o `build`, que agora compila apenas `custom/`.
+ */
+/**
+ * A `version` não é enfeite: sem ela o npm não consegue formar `nome@versão` e todo aviso dele sobre
+ * este pacote sai com `package: undefined`, o que faz parecer que o arquivo está corrompido.
+ *
+ * `engines.node` vem do repositório e descreve o RUNTIME das Cloud Functions — é por ele que o Firebase
+ * escolhe em qual Node a function roda. Ele não descreve a máquina de quem instala, e é por isso que o
+ * npm avisa `EBADENGINE` quando as duas versões diferem: o aviso é esperado e não impede nada. Trocar
+ * o valor por uma faixa (`>=22`) calaria o aviso e passaria a deixar a escolha do runtime ambígua para
+ * o Firebase — o preço errado pela linha de saída.
+ */
+export const packageFunctionsPackageJson = (source, version) => JSON.stringify({
+    name: 'microteia-functions',
+    version,
+    private: true,
+    main: 'index.js',
+    engines: source.engines ?? { node: '22' },
+    scripts: {
+        build: 'tsc -p custom/tsconfig.json',
+    },
+    dependencies: source.dependencies ?? {},
+    devDependencies: source.devDependencies ?? {},
+}, null, 2) + '\n';
+/**
+ * Entrypoint da instalação. O espalhamento mantém os nomes PLANOS (`onUserCreated`, e não
+ * `kernel-onUserCreated`), que é o que os deploys por nome e os gatilhos já existentes esperam.
+ */
+export const packageFunctionsIndexJs = () => `// Generated by "microteia pack". Do not edit.
+//
+// The deployed function set is the compiled kernel plus whatever this installation added under
+// custom/. Kernel functions cannot be overridden here: custom/ is spread last, so a name collision
+// would silently replace a kernel trigger — keep your function names distinct.
+const kernel = require('./lib/index.js');
+const custom = require('./custom/lib/index.js');
+
+module.exports = { ...kernel, ...custom };
+`;
+/**
+ * O `exclude` é cinto de segurança, não redundância: o `gatherCustomFunctions` já não copia teste para
+ * cá, mas ele reconhece as duas convenções usuais (`*.test.ts`, `__tests__/`) e um arquivo fora delas
+ * chegaria. Aqui ele chega e não compila — o que é um upload maior, e não um deploy quebrado.
+ */
+export const packageCustomTsconfig = () => JSON.stringify({
+    compilerOptions: {
+        module: 'commonjs',
+        moduleResolution: 'node',
+        target: 'es2022',
+        lib: ['ES2022'],
+        types: ['node'],
+        rootDir: 'src',
+        outDir: 'lib',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        sourceMap: true,
+        noImplicitReturns: true,
+    },
+    include: ['src'],
+    exclude: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx', '**/__tests__/**'],
+}, null, 2) + '\n';
+export const packageCustomIndexTs = () => `// Cloud Functions belonging to this installation.
+//
+// Everything exported from this file is deployed alongside the Microteia kernel and survives a
+// kernel upgrade — "microteia deploy" replaces lib/ but never touches custom/.
+//
+// Functions must be pinned to the same region as the rest of the installation, otherwise Firestore
+// triggers will not fire. Example:
+//
+//   import { onCall } from 'firebase-functions/v2/https';
+//
+//   export const helloOffice = onCall({ region: 'southamerica-east1', cors: true }, () => {
+//     return { ok: true };
+//   });
+
+export {};
+`;
+export const CONSOLE_PACKAGE_NAME = '@microteia/console';
+/**
+ * O Console empacotado para rodar FORA do repositório — e agora publicável.
+ *
+ * O `type: module` não é detalhe: o compilado é ESM, e sem esta declaração o Node só o carrega por
+ * adivinhação de sintaxe — que existe a partir do 22.7 e falha em silêncio nas versões anteriores, com
+ * "Cannot use import statement outside a module". O `bin` é o que dá o comando `microteia` global.
+ *
+ * Ele deixou de ser `private`, e isso resolve um ovo-e-galinha: enquanto o Console também tinha de ser
+ * baixado de algum lugar, alguém precisava baixar o baixador — e o primeiro passo de quem instala era
+ * uma pasta recebida por e-mail e um `ln -s` escrito à mão. Publicado, o registry já dá URL versionada,
+ * impressão digital no lock, CDN e `npm outdated`, que era tudo o que o canal precisaria reimplementar.
+ *
+ * `files` é a lista exata, e o `CONSOLE-VERSIONS.md` está nela por um motivo que não é documentação: o
+ * `unpack` lê aquele arquivo AO LADO do binário que está rodando para pô-lo na raiz da instalação. Fora
+ * de `files`, ele não existe numa instalação global, e o comando passa a avisar que o Console não carrega
+ * histórico — na máquina do escritório, e só lá.
+ */
+export const consolePackageJson = (version) => JSON.stringify({
+    name: CONSOLE_PACKAGE_NAME,
+    version,
+    description: 'Install and update Microteia in a Firebase project you own.',
+    license: 'UNLICENSED',
+    type: 'module',
+    bin: { microteia: 'lib/index.js' },
+    files: ['lib', 'README.md', 'CONSOLE-VERSIONS.md'],
+    engines: { node: '>=22' },
+    publishConfig: { access: 'public' },
+}, null, 2) + '\n';
+export const consoleReadme = (version) => `# Microteia Console ${version}
+
+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.
+
+## Installing it
+
+    npm i -g ${CONSOLE_PACKAGE_NAME}
+    microteia --help
+
+Or run it without installing anything:
+
+    npx ${CONSOLE_PACKAGE_NAME} --help
+
+Where npm's global prefix belongs to root — Node installed system-wide under \`/usr/local\` — the global
+install fails with EACCES. Point npm at a prefix of your own instead of reaching for sudo, which would
+write root-owned files that then need sudo to remove:
+
+    npm config set prefix ~/.npm-global
+    export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc
+
+This folder also runs as it is, with no npm at all:
+
+    node lib/index.js --help
+
+## Using it
+
+    microteia init --name "<office>"
+    microteia connect --project <your-firebase-project-id>
+    microteia unpack --version latest
+    microteia deploy
+
+\`connect\` prints everything that has to be prepared in the Firebase project first — start with the
+Blaze plan, since nothing else can be created without it.
+
+\`unpack --version\` reads the published catalog, downloads the version and checks its sha256 before
+touching what is installed. On a machine that cannot reach the catalog, name a file you already have:
+
+    microteia unpack --kernel <microteia-kernel-x.y.z>.tgz
+
+\`microteia --version\` answers what is installed here, and says so when a newer kernel is published.
+
+Later, whenever an office installs an extension that needs server-side resources, run:
+
+    microteia provision
+
+The extension shows "Backend pending" in the application until you do, and stays out of the menu.
+
+## What has to exist on this machine
+
+| Tool          | Used for                                                       |
+| ------------- | -------------------------------------------------------------- |
+| Node.js 22+   | running this Console (newer is fine; the functions' own runtime is pinned to 22) |
+| \`firebase\`    | every deploy — authenticate with \`firebase login\` first          |
+| \`npm\`, \`tar\` | installing the functions' dependencies and unpacking the kernel  |
+| \`gcloud\`      | creating the App Engine application, and reading which extensions an office installed (\`gcloud auth login\`) |
+
+The \`pack\` and \`publish\` commands in here build and release the platform itself, and only work inside
+the Microteia repository.
+
+## What changed in this Console
+
+\`CONSOLE-VERSIONS.md\`, in this folder. \`unpack\` copies it into the installation it manages, beside the
+platform's own \`KERNEL-VERSIONS.md\` — each history travels with the artifact it describes.
+`;

package/lib/vendor/pluginWorkspaceTemplates.d.ts

@@ -0,0 +1,19 @@
+/**
+ * O pouco que o CONSOLE sabe sobre `extensions/`.
+ *
+ * Tudo o que descreve o kernel — `AGENTS.md`, `AUTHORING.md`, `tsconfig.json`, `.mcp.json`, os scripts
+ * — morava aqui, e era o lado errado. O Console é versionado (`CLI_VERSION`) e distribuído SEPARADAMENTE
+ * do kernel: um Console de duas versões atrás ao lado de uma instalação nova escrevia, em silêncio, a
+ * documentação de outro contrato. Passou para `src/sdk/node/workspace/`, que viaja no mesmo `.tgz` que
+ * os pontos de extensão que o texto descreve, e é reescrito a cada troca de kernel.
+ *
+ * Sobrou o que só o Console tem como saber: onde está o tarball do SDK dentro do pacote, e o nome do
+ * escritório. É a semente — mínima de propósito, porque quem a completa é o `sync`.
+ */
+export declare const SDK_TARBALL = "microteia-sdk.tgz";
+/**
+ * A semente do `package.json`. Não traz scripts nem devDependencies: os nomes de comando são do SDK, e
+ * duplicá-los aqui era exatamente o problema. O `sync` os acrescenta logo depois do `npm install`, e o
+ * segundo `npm install` os instala.
+ */
+export declare const workspacePackageJson: (officeName: string, sdkPath: string) => string;