@microteia/console 2.38.0 → 2.42.0

package/lib/console/exportCatalog.js

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { flagValue } from '../shared/args.js';
 import { CLI_VERSION } from '../shared/paths.js';
@@ -21,7 +22,11 @@ import { WORKSPACE_DIR } from './workspace.js';
  * A saída NÃO foi ligar o SDK ao Firestore. `microteia-plugin` é offline por desenho, e arrastar
  * credencial para dentro da ferramenta de autoria trocaria uma cegueira por um problema pior. Quem já
  * fala com o projeto do escritório é o Console — o token vem do `gcloud`, a cada execução, e nada é
- * guardado. Então é o Console que lê e escreve o arquivo, e o SDK apenas o encontra ali.
+ * guardado. O Console LÊ; quem monta o arquivo é o escritor do SDK instalado (ver `loadCatalogWriter`).
+ *
+ * O token do `gcloud` é credencial de PROJETO: não passa pelas Security Rules, e por isso exige papel
+ * no Firebase inteiro. Quem administra só o escritório tira o mesmo retrato pela aplicação (Extensões →
+ * Exportar catálogo), lendo como membro, sob as regras.
  *
  * Três decisões que não são preferência:
  *
@@ -34,313 +39,50 @@ import { WORKSPACE_DIR } from './workspace.js';
  *   adivinhação escreveria o vocabulário de um dentro do trabalho de outro. Sem a opção, o comando
  *   LISTA os que existem.
  */
-/** O nome é contrato com o SDK, que o procura por este nome — ver `installedCatalog.ts` do kernel. */
-export const CATALOG_FILE = 'installed-catalog.json';
 /**
- * A versão do FORMATO. Ela existe para que um Console de outra época não seja lido como se falasse a
- * mesma língua: o SDK recusa o que não for exatamente esta, e diz o comando que refaz o arquivo.
+ * O nome do arquivo que o SDK procura. O valor de verdade vem do SDK carregado; este é só o que se diz
+ * ao autor ANTES de o SDK ter sido encontrado.
  */
-export const CATALOG_FORMAT_VERSION = 1;
-const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value : undefined);
-const asRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? value
-    : undefined);
-const FIELD_ORIGINS = ['builtin', 'plugin', 'design'];
+const CATALOG_FILE_HINT = 'installed-catalog.json';
 /**
- * A superfície exportada de uma cópia instalada: os ids de `manifest.exports`, cada um casado com o
- * artefato do pacote que o atende, para ganhar tipo e nome.
+ * O escritor do retrato, carregado do SDK que o escritório tem em `extensions/`.
  *
- * O Console não alcança `src/` — logo não há `MarketplacePlugin` tipado aqui, e a leitura é do
- * documento cru, como todo o resto deste arquivo. Um export que não casa com nada continua na lista
- * como `unknown`: a extensão está declarando algo que não entrega, e esconder isso do autor apenas
- * adia a descoberta para a primeira execução.
- */
-const exportedArtifacts = (extension) => {
-    const declared = extension.manifest?.exports;
-    if (!Array.isArray(declared))
-        return [];
-    const pkg = asRecord(extension.data.package) ?? {};
-    const named = new Map();
-    const collect = (raw, kind) => {
-        for (const one of Array.isArray(raw) ? raw : []) {
-            const record = asRecord(one);
-            const id = text(record?.templateId);
-            if (id === undefined || named.has(id))
-                continue;
-            named.set(id, { id, kind, name: text(record?.name) ?? text(record?.title) ?? id });
-        }
-    };
-    collect(pkg.workflows, 'workflow');
-    collect(pkg.actions, 'action');
-    collect(pkg.scripts, 'script');
-    return declared
-        .filter((id) => typeof id === 'string' && id !== '')
-        .map((id) => named.get(id) ?? { id, kind: 'unknown', name: id })
-        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-};
-const NAV_GROUP_POINT = 'ui.nav.group';
-const MESSAGES_POINT = 'i18n.messages';
-const DEFAULT_LOCALE = 'en';
-const MESSAGE_REFERENCE = /^@([a-z0-9.-]+)\/(.+)$/;
-/**
- * Os grupos da barra lateral de uma cópia instalada, com o nome resolvido pelos `i18n.messages` do
- * próprio manifesto. É a mesma leitura que `declaredNavGroupsOf` faz no kernel, repetida porque o
- * Console não alcança `src/` — e é o teste que atravessa a fronteira que confere as duas.
- */
-const navGroupsOf = (extension) => {
-    const contributes = Array.isArray(extension.manifest?.contributes) ? extension.manifest.contributes : [];
-    const contributions = contributes.map(asRecord).filter((one) => one !== undefined);
-    const bundles = contributions
-        .filter((one) => one.point === MESSAGES_POINT)
-        .map((one) => asRecord(one.metadata))
-        .filter((one) => one !== undefined);
-    const translationsOf = (label) => {
-        const match = MESSAGE_REFERENCE.exec(label);
-        if (!match)
-            return {};
-        const found = {};
-        for (const bundle of bundles) {
-            const locale = text(bundle.locale);
-            const message = asRecord(bundle.messages)?.[match[2]];
-            if (bundle.namespace !== match[1] || locale === undefined || typeof message !== 'string' || message.trim() === '')
-                continue;
-            if (found[locale] === undefined)
-                found[locale] = message;
-        }
-        return found;
-    };
-    return contributions
-        .filter((one) => one.point === NAV_GROUP_POINT)
-        .flatMap((one) => {
-        const metadata = asRecord(one.metadata) ?? {};
-        const key = text(metadata.key)?.trim();
-        if (key === undefined)
-            return [];
-        const raw = text(metadata.label) ?? key;
-        const translations = translationsOf(raw);
-        return [{
-                key,
-                label: translations[DEFAULT_LOCALE] ?? Object.values(translations)[0] ?? raw,
-                translations,
-                order: typeof metadata.order === 'number' ? metadata.order : 0,
-            }];
-    });
-};
-const DOCUMENT_TEMPLATE_POINT = 'document.template';
-const documentParameterOf = (raw) => {
-    const record = asRecord(raw);
-    const key = text(record?.key);
-    const type = text(record?.type);
-    if (record === undefined || key === undefined || type === undefined)
-        return [];
-    const entityType = text(record.entityType);
-    return [{
-            key,
-            type,
-            ...(record.required === true ? { required: true } : {}),
-            ...(record.list === true ? { list: true } : {}),
-            ...(entityType === undefined ? {} : { entityType }),
-        }];
-};
-/**
- * Os modelos de documento de uma cópia instalada, como contrato. É a mesma leitura que
- * `documentTemplateContractOf` faz no kernel, repetida porque o Console não alcança `src/` — e é o
- * teste que atravessa a fronteira que confere as duas.
- */
-const documentTemplatesOf = (extension) => {
-    const contributes = Array.isArray(extension.manifest?.contributes) ? extension.manifest.contributes : [];
-    return contributes
-        .map(asRecord)
-        .filter((one) => one?.point === DOCUMENT_TEMPLATE_POINT)
-        .flatMap((one) => {
-        const metadata = asRecord(one.metadata);
-        const key = text(metadata?.key);
-        if (metadata === undefined || key === undefined)
-            return [];
-        return [{
-                key,
-                source: metadata.source === 'payload' ? 'payload' : 'record',
-                parameters: (Array.isArray(metadata.parameters) ? metadata.parameters : []).flatMap(documentParameterOf),
-            }];
-    })
-        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-};
-const FIELD_PRESET_POINT = 'data.field.preset';
-/**
- * Os presets de campo de uma cópia instalada. É a mesma leitura que `declaredFieldPresets` faz no
- * kernel — chave e rótulo obrigatórios, e as partes pelo critério do editor de campo —, repetida porque
- * o Console não alcança `src/`; o teste que atravessa a fronteira confere as duas.
- */
-const fieldPresetsOf = (extension) => {
-    const contributes = Array.isArray(extension.manifest?.contributes) ? extension.manifest.contributes : [];
-    return contributes
-        .map(asRecord)
-        .filter((one) => one?.point === FIELD_PRESET_POINT)
-        .flatMap((one) => {
-        const metadata = asRecord(one.metadata);
-        const key = text(metadata?.key);
-        if (metadata === undefined || key === undefined || text(metadata.label) === undefined)
-            return [];
-        return [{
-                key,
-                slots: [
-                    ...(metadata.mask ? ['mask'] : []),
-                    ...(Array.isArray(metadata.format) && metadata.format.length > 0 ? ['format'] : []),
-                    ...(metadata.validate ? ['validate'] : []),
-                ],
-            }];
-    })
-        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-};
-/**
- * A mesma dedução que a aplicação faz ao ler a tela (`screenDefinitionMapper.ts`): o `origin` gravado
- * quando ele existe, senão `plugin` para quem tem dono e `design` para o que o escritório criou. Ela é
- * repetida aqui porque o Console não alcança `src/` — e é conferida contra a instalação real por teste.
+ * O Console trazia uma CÓPIA do escritor, e o leitor morava no SDK: os dois lados eram compilados
+ * separadamente e casados só por teste, e o Console é distribuído à parte do kernel. Carregar o
+ * escritor de onde mora o leitor faz o formato ter um dono só — e é a mesma função que a aplicação usa
+ * no botão Exportar catálogo da tela de Extensões.
+ *
+ * O SDK de um kernel anterior a esse escritor não o tem, e aí o comando RECUSA dizendo como trazê-lo,
+ * em vez de escrever com uma cópia que já não é conferida contra nada.
  */
-const originOf = (data, fallback) => {
-    const declared = text(data.origin);
-    if (declared !== undefined && FIELD_ORIGINS.includes(declared))
-        return declared;
-    return text(data.ownerPluginId) !== undefined ? 'plugin' : fallback;
-};
-const fieldExport = (raw, index, screenOrigin) => {
-    const field = asRecord(raw);
-    if (field === undefined)
-        return null;
-    const key = text(field.key);
-    if (key === undefined)
-        return null;
-    const logic = asRecord(field.logic);
-    const compute = text(logic?.compute);
-    return {
-        key,
-        label: text(field.label) ?? key,
-        type: text(field.type) ?? 'text',
-        required: field.required === true,
-        order: typeof field.order === 'number' ? field.order : index,
-        ...(field.multi === true ? { multi: true } : {}),
-        ...(text(field.refEntity) === undefined ? {} : { refEntity: text(field.refEntity) }),
-        ...(text(field.refDenormKey) === undefined ? {} : { refDenormKey: text(field.refDenormKey) }),
-        ...(text(field.lookupCollection) === undefined ? {} : { lookupCollection: text(field.lookupCollection) }),
-        ...(text(field.section) === undefined ? {} : { section: text(field.section) }),
-        origin: originOf(field, screenOrigin),
-        ...(text(field.ownerPluginId) === undefined ? {} : { ownerPluginId: text(field.ownerPluginId) }),
-        ...(asRecord(field.aggregation) === undefined ? {} : { aggregation: asRecord(field.aggregation) }),
-        ...(compute === undefined ? {} : { compute }),
-        ...(field.unique === true ? { unique: true } : {}),
-    };
-};
-const normalizeExport = (raw) => {
-    const normalize = asRecord(raw);
-    if (normalize === undefined)
-        return undefined;
-    const formatPreset = text(normalize.formatPreset);
-    const picked = {
-        ...(typeof normalize.trim === 'boolean' ? { trim: normalize.trim } : {}),
-        ...(typeof normalize.caseInsensitive === 'boolean' ? { caseInsensitive: normalize.caseInsensitive } : {}),
-        ...(formatPreset === undefined ? {} : { formatPreset }),
-    };
-    return Object.keys(picked).length > 0 ? picked : undefined;
-};
-/** A chave como o kernel a grava, sem o que é apresentação. Sem nome ou sem campo, não é chave. */
-const keyExport = (raw) => {
-    const key = asRecord(raw);
-    const name = text(key?.name);
-    const kind = text(key?.kind);
-    const fields = (Array.isArray(key?.fields) ? key.fields : []).filter((one) => typeof one === 'string' && one !== '');
-    if (key === undefined || name === undefined || kind === undefined || fields.length === 0)
-        return null;
-    const normalize = normalizeExport(key.normalize);
-    return {
-        name,
-        kind,
-        fields,
-        ...(text(key.scope) === undefined ? {} : { scope: text(key.scope) }),
-        ...(normalize === undefined ? {} : { normalize }),
-        ...(typeof key.sparse === 'boolean' ? { sparse: key.sparse } : {}),
-        ...(text(key.ownerPluginId) === undefined ? {} : { ownerPluginId: text(key.ownerPluginId) }),
-    };
-};
-const screenExport = (document) => {
-    const data = document.data;
-    const origin = originOf(data, 'design');
-    const fields = Array.isArray(data.fields) ? data.fields : [];
+export const loadCatalogWriter = (directory) => {
+    if (!existsSync(join(directory, 'node_modules', '@microteia', 'sdk'))) {
+        throw new Error(`The authoring SDK is not installed in ${EXTENSIONS_DIR}/, and it is the SDK that writes the catalog —\n`
+            + '  the same one that reads it. Run "microteia plugin-init" (or "npm install" inside it), then run this again.');
+    }
+    const sdk = createRequire(join(directory, 'package.json'))('@microteia/sdk');
+    const build = sdk.buildInstalledCatalog;
+    const serialize = sdk.serializeInstalledCatalog;
+    const file = sdk.INSTALLED_CATALOG_FILE;
+    if (typeof build !== 'function' || typeof serialize !== 'function' || typeof file !== 'string') {
+        throw new Error(`The authoring SDK in ${EXTENSIONS_DIR}/ is older than the catalog writer this Console relies on.\n`
+            + '  Install a newer kernel ("microteia unpack --version latest"), which brings an SDK that writes it.\n'
+            + '  Without access to the Firebase project, "Export catalog" on the Extensions screen of the\n'
+            + '  application writes the same file, once the installation runs a kernel that has it.');
+    }
     return {
-        key: document.id,
-        ...(text(data.sourceId) === undefined ? {} : { sourceId: text(data.sourceId) }),
-        ...(text(data.dataCollection) === undefined ? {} : { collection: text(data.dataCollection) }),
-        titleSingular: text(data.titleSingular) ?? document.id,
-        ...(text(data.titlePlural) === undefined ? {} : { titlePlural: text(data.titlePlural) }),
-        titleFieldKey: text(data.titleFieldKey) ?? '',
-        origin,
-        ...(text(data.ownerPluginId) === undefined ? {} : { ownerPluginId: text(data.ownerPluginId) }),
-        ...(text(data.parentEntity) === undefined ? {} : { parentEntity: text(data.parentEntity) }),
-        ...(text(data.parentFieldKey) === undefined ? {} : { parentFieldKey: text(data.parentFieldKey) }),
-        ...(text(data.parentRelation) === undefined ? {} : { parentRelation: text(data.parentRelation) }),
-        ...(text(data.tagCollection) === undefined ? {} : { tagCollection: text(data.tagCollection) }),
-        ...(text(data.eventPrefix) === undefined ? {} : { eventPrefix: text(data.eventPrefix) }),
-        keys: (Array.isArray(data.keys) ? data.keys : [])
-            .map(keyExport)
-            .filter((key) => key !== null),
-        fields: fields
-            .map((field, index) => fieldExport(field, index, origin))
-            .filter((field) => field !== null),
+        file,
+        build: build,
+        serialize: serialize,
     };
 };
-/**
- * O id do documento É o nome da coleção da lista, tanto em `lookupDefinitions` quanto em
- * `tagDefinitions` — a mesma convenção que os repositórios da aplicação usam ao mapeá-las.
- */
-const listExport = (document) => ({
-    collection: document.id,
-    label: text(document.data.label) ?? document.id,
-    ...(text(document.data.ownerPluginId) === undefined
-        ? {}
-        : { ownerPluginId: text(document.data.ownerPluginId) }),
-});
-/**
- * O documento, montado a partir do que foi lido. É PURA de propósito: o que ela produz é o contrato com
- * o SDK, e um contrato que só pode ser exercitado com um projeto Firebase na frente é um contrato que
- * ninguém confere.
- *
- * Uma tela DESLIGADA (`enabled: false`) fica de fora: a coleção dela pode até existir no banco, mas
- * nada da plataforma a desenha, e trazê-la faria o catálogo afirmar que a entidade existe. Uma tela de
- * extensão DESATIVADA continua: o documento dela segue gravado, e é ele que explica um campo que o
- * autor vai encontrar.
- */
-export const buildCatalogExport = (input) => ({
-    version: CATALOG_FORMAT_VERSION,
-    projectId: input.projectId,
-    tenantId: input.tenant.id,
-    tenantName: input.tenant.name,
-    exportedAt: input.exportedAt.toISOString(),
-    kernelVersion: input.kernelVersion,
-    consoleVersion: CLI_VERSION,
-    extensions: input.extensions
-        .map((one) => ({
-        id: one.id,
-        name: one.name,
-        version: one.version,
-        active: one.active,
-        exports: exportedArtifacts(one),
-        navGroups: navGroupsOf(one),
-        documentTemplates: documentTemplatesOf(one),
-        fieldPresets: fieldPresetsOf(one),
-    }))
-        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
-    screens: input.screens
-        .filter((document) => document.data.enabled !== false)
-        .map(screenExport)
-        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)),
-    lookups: input.lookups
-        .map(listExport)
-        .sort((a, b) => (a.collection < b.collection ? -1 : a.collection > b.collection ? 1 : 0)),
-    tagLists: input.tagLists
-        .map(listExport)
-        .sort((a, b) => (a.collection < b.collection ? -1 : a.collection > b.collection ? 1 : 0)),
-});
 const decode = (documents) => documents.map((document) => ({ id: documentId(document), data: decodeFields(document.fields) }));
 const readSubcollection = async (projectId, tenantId, name) => decode(await listDocuments(projectId, `/tenants/${tenantId}/${name}`));
+/** A cópia instalada como está gravada: o escritor lê o manifesto de dentro de `package`, como o kernel. */
+const storedExtension = (extension) => ({
+    id: extension.documentId,
+    data: extension.data,
+});
 /**
  * O kernel que está NO LUGAR nesta instalação, e não o que já foi publicado: o retrato descreve o
  * contrato contra o qual o autor compila agora. Ausente, o SDK dirá que não sabe — o que é melhor que
@@ -364,14 +106,14 @@ const installedKernelVersion = async (root) => {
  * ainda não chegou (um diretório sincronizado por um kernel anterior), diz qual comando a traz, em vez
  * de deixar o retrato pronto para ser commitado sem ninguém notar.
  */
-const checkIgnored = async (directory) => {
+const checkIgnored = async (directory, catalogFile) => {
     const path = join(directory, '.gitignore');
     if (!existsSync(path))
         return;
     const lines = (await readFile(path, 'utf8')).split('\n').map((line) => line.trim());
-    if (lines.includes(CATALOG_FILE) || lines.includes('*.json'))
+    if (lines.includes(catalogFile) || lines.includes('*.json'))
         return;
-    warn(`${relative(process.cwd(), path) || '.gitignore'} does not ignore ${CATALOG_FILE}.`);
+    warn(`${relative(process.cwd(), path) || '.gitignore'} does not ignore ${catalogFile}.`);
     info('  It carries screen and field names the office typed, which is tenant data and does not belong');
     info(`  in an extension repository. Run "npm run sync" in ${EXTENSIONS_DIR}/ to get the line, or add it`);
     info('  by hand.');
@@ -412,12 +154,14 @@ export const exportCatalog = async (args) => {
     }
     const output = flagValue(args, 'output');
     const directory = join(root, EXTENSIONS_DIR);
-    if (output === undefined && !existsSync(directory)) {
+    // Mesmo com `--output`: o escritor mora no SDK de `extensions/`, e sem ele não há o que escrever.
+    if (!existsSync(directory)) {
         throw new Error(`There is no ${EXTENSIONS_DIR}/ in this installation, and that is where the catalog belongs — it\n`
-            + '  exists to answer the authoring tools, and nothing else reads it.\n'
-            + '  Run "microteia plugin-init" first, or pass --output <path> to put it somewhere else.');
+            + `  exists to answer the authoring tools, and the SDK there is what writes ${CATALOG_FILE_HINT}.\n`
+            + '  Run "microteia plugin-init" first.');
     }
-    const target = output === undefined ? join(directory, CATALOG_FILE) : resolve(output);
+    const writer = loadCatalogWriter(directory);
+    const target = output === undefined ? join(directory, writer.file) : resolve(output);
     step(1, 2, `Reading what ${tenant.name} has`);
     const [screens, lookups, tagLists, extensions] = await Promise.all([
         readSubcollection(projectId, tenant.id, 'screenDefinitions'),
@@ -425,21 +169,22 @@ export const exportCatalog = async (args) => {
         readSubcollection(projectId, tenant.id, 'tagDefinitions'),
         readInstalledExtensions(projectId, tenant.id),
     ]);
-    const document = buildCatalogExport({
+    const document = writer.build({
         projectId,
         tenant,
         kernelVersion: await installedKernelVersion(root),
         exportedAt: new Date(),
+        exporter: { tool: 'console', version: CLI_VERSION },
         screens,
         lookups,
         tagLists,
-        extensions,
+        extensions: extensions.map(storedExtension),
     });
     step(2, 2, 'Writing the snapshot');
     await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, `${JSON.stringify(document, null, 2)}\n`);
+    await writeFile(target, writer.serialize(document));
     const fromExtensions = document.screens.filter((screen) => screen.origin === 'plugin').length;
-    success(`${relative(process.cwd(), target) || CATALOG_FILE} — ${document.screens.length} screen(s), `
+    success(`${relative(process.cwd(), target) || writer.file} — ${document.screens.length} screen(s), `
         + `${document.lookups.length} list(s), ${document.tagLists.length} tag list(s)`);
     info(`  ${fromExtensions} screen(s) come from the ${document.extensions.length} installed extension(s); `
         + `the rest the office built itself.`);
@@ -450,7 +195,7 @@ export const exportCatalog = async (args) => {
     const templates = document.extensions.reduce((total, one) => total + one.documentTemplates.length, 0);
     info(`  ${templates} document template(s) are declared, with the shape of their parameters, for other extensions to generate.`);
     blank();
-    await checkIgnored(directory);
+    await checkIgnored(directory, writer.file);
     info('It is a SNAPSHOT, and it says so: the authoring tools report when it was taken and warn when it');
     info('is old. Nothing keeps it in step with the office — run this again after screens change there.');
     blank();

package/lib/console/firestoreRest.d.ts

@@ -20,6 +20,8 @@ export declare const decodeFields: (fields: Record<string, unknown>) => Record<s
  * erro. Documento de extensão é grande, mas são poucos por escritório, e isto roda uma vez por comando.
  */
 export declare const listDocuments: (projectId: string, path: string) => Promise<FirestoreDocument[]>;
+/** Os campos de UM documento, decodificados — `null` quando ele não existe. */
+export declare const getDocument: (projectId: string, path: string) => Promise<Record<string, unknown> | null>;
 export declare const documentId: (document: FirestoreDocument) => string;
 /** Um valor com o tipo que a REST espera, montado por quem sabe o que o campo é. */
 export type FirestoreTypedValue = {

package/lib/console/firestoreRest.js

@@ -62,6 +62,10 @@ const request = async (projectId, path, init = { method: 'GET' }) => {
         ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
     });
     const text = await response.text();
+    // Documento que ainda não existe é resposta, não falha, para quem pediu assim: é o caso de todo
+    // documento que o Console escreve pela primeira vez num projeto que nunca o recebeu.
+    if (response.status === 404 && init.allowMissing === true)
+        return null;
     if (!response.ok) {
         const detail = text.slice(0, 400);
         if (response.status === 403) {
@@ -113,13 +117,20 @@ export const listDocuments = async (projectId, path) => {
             method: 'GET',
             query: { pageSize: '300', ...(pageToken === undefined ? {} : { pageToken }) },
         });
-        for (const entry of page.documents ?? []) {
+        for (const entry of page?.documents ?? []) {
             documents.push({ name: entry.name, fields: entry.fields ?? {} });
         }
-        pageToken = page.nextPageToken;
+        pageToken = page?.nextPageToken;
     } while (pageToken !== undefined);
     return documents;
 };
+/** Os campos de UM documento, decodificados — `null` quando ele não existe. */
+export const getDocument = async (projectId, path) => {
+    const document = await request(projectId, path, { method: 'GET', allowMissing: true });
+    if (document === null)
+        return null;
+    return decodeFields(document.fields ?? {});
+};
 export const documentId = (document) => document.name.slice(document.name.lastIndexOf('/') + 1);
 export const asString = (value) => ({ stringValue: value });
 /**

package/lib/console/installedExtensions.d.ts

@@ -16,6 +16,8 @@ export interface TenantSummary {
 export interface InstalledExtensionRecord {
     tenantId: string;
     documentPath: string;
+    /** O id do documento, que pode diferir do `manifest.id` — é por ele que a cópia é endereçada. */
+    documentId: string;
     id: string;
     name: string;
     version: string;

package/lib/console/installedExtensions.js

@@ -26,6 +26,7 @@ export const readInstalledExtensions = async (projectId, tenantId) => {
         return {
             tenantId,
             documentPath: `/tenants/${tenantId}/installed_extensions/${fallbackId}`,
+            documentId: fallbackId,
             id: String(manifest?.id ?? fallbackId),
             name: String(manifest?.name ?? manifest?.id ?? fallbackId),
             version: String(manifest?.version ?? '0.0.0'),