@microteia/console 2.28.0 → 2.29.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,15 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.29.0] — 2026-10-15
+
+- feat(export-catalog): each installed extension now carries `navGroups` — the sidebar groups it declares, by key, with the name resolved in every language the package ships and its order. The authoring tools list them in `microteia://nav-groups`, so an extension joins an existing group instead of drawing a second one with the same title. Always written, even empty; a snapshot taken by an older Console is read as "groups unknown".
+
+#### [2.28.1] — 2026-10-14
+
+- fix(console/deploy): a function whose source declares `retry: true` is no longer refused on its first deploy. Without a terminal the Firebase CLI does not ask "Would you like to proceed with deployment?" — it aborts with "Pass the --force option to deploy functions with a failure policy", so `runAggregateBackfill` and `runRecordKeyAdoption` never went up through `microteia deploy` or `provision`. That one function is now redeployed with `--force`, and only when the project is known to hold no copy of it in another region: the same flag would delete that copy without asking, which stays a `--prune` decision. When a copy stands or the project could not be listed, the refusal is terminal and the hint points to `microteia deploy --prune`.
+- refactor(console/regionOrphans): `clearRegionOrphans` returns the names whose old-region copy is still standing (`null` when the project could not be listed) instead of a boolean.
+
 #### [2.28.0] — 2026-10-13
 
 - feat(examples): the Console ships `business-days` as authoring source — a collection the kernel reads without knowing its name (`time.business.calendar`), and a code view that edits data no field type describes.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.28.0
+# Microteia Console 2.29.0
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/deploy.js

@@ -185,7 +185,7 @@ export const deploy = async (args) => {
             // ANTES de deployar: uma cópia da mesma function numa região que o pacote abandonou faz o
             // `firebase` recusar o deploy dela, tentativa após tentativa, e faz um gatilho de Firestore
             // disparar duas vezes por gravação enquanto ninguém percebe.
-            await clearRegionOrphans(projectId, own, region, hasFlag(args, 'prune'), deployedNow);
+            const standingCopies = await clearRegionOrphans(projectId, own, region, hasFlag(args, 'prune'), deployedNow);
             // Numa instalação nova não há carimbo nenhum com que comparar, e o mecanismo cai sozinho no
             // caminho de sempre — não é preciso um desvio para isso. `--all` é o pedido explícito de subir
             // tudo, para a configuração trocada por fora, que carimbo nenhum enxerga.
@@ -194,6 +194,7 @@ export const deploy = async (args) => {
                 cwd: install,
                 delaySeconds,
                 force: firstInstall,
+                standingCopies,
             }, { deployed: deployedNow, region, all: hasFlag(args, 'all') });
             refreshedStamps = report.refreshed;
             skippedFunctions = report.skipped.length;

package/lib/console/deployFunctions.d.ts

@@ -4,6 +4,11 @@ export interface FunctionDeployOptions {
     delaySeconds: number;
     /** `--force` deixa o Firebase configurar sozinho a política de limpeza do Artifact Registry. */
     force: boolean;
+    /**
+     * As functions que ainda têm cópia numa região abandonada, como `clearRegionOrphans` devolve;
+     * `null` quando não deu para saber. Só fora dele a recusa da política de repetição é contornada.
+     */
+    standingCopies: ReadonlySet<string> | null;
 }
 export interface FunctionDeployFailure {
     name: string;
@@ -39,7 +44,20 @@ export interface TerminalFailure {
     match: RegExp;
     hint: string[];
 }
+/**
+ * A recusa do `firebase` sem terminal diante de uma function que passa a ter `retry`.
+ *
+ * Com terminal ele pergunta "Would you like to proceed with deployment?"; sem, recusa e pede
+ * `--force`. A pergunta é sobre o que o PRÓPRIO código declarou (`retry: true` no gatilho), e quem
+ * declarou já respondeu: repetir a entrega é o que torna o gatilho confiável. Por isso a recusa é
+ * contornada com `--force` naquela function, e só nela — e só quando não há cópia dela em outra
+ * região, porque o mesmo `--force` faria o `firebase` apagar essa cópia sem perguntar.
+ *
+ * A pergunta só existe na primeira vez: com a function no ar já com `retry`, ela não volta.
+ */
+export declare const FAILURE_POLICY_REFUSAL: RegExp;
 export declare const terminalFailure: (output: string) => TerminalFailure | undefined;
+export declare const mayConfirmRetryPolicy: (name: string, output: string, options: FunctionDeployOptions) => boolean;
 export declare const deployFunctionsOneByOne: (names: string[], options: FunctionDeployOptions) => Promise<FunctionDeployReport>;
 export declare const reportFailures: (failures: FunctionDeployFailure[]) => void;
 export declare const reportNotices: (notices: string[]) => void;

package/lib/console/deployFunctions.js

@@ -64,6 +64,18 @@ export const failureReason = (output) => {
         ?? 'no output from firebase';
     return chosen.length > REASON_LIMIT ? `${chosen.slice(0, REASON_LIMIT - 1)}…` : chosen;
 };
+/**
+ * A recusa do `firebase` sem terminal diante de uma function que passa a ter `retry`.
+ *
+ * Com terminal ele pergunta "Would you like to proceed with deployment?"; sem, recusa e pede
+ * `--force`. A pergunta é sobre o que o PRÓPRIO código declarou (`retry: true` no gatilho), e quem
+ * declarou já respondeu: repetir a entrega é o que torna o gatilho confiável. Por isso a recusa é
+ * contornada com `--force` naquela function, e só nela — e só quando não há cópia dela em outra
+ * região, porque o mesmo `--force` faria o `firebase` apagar essa cópia sem perguntar.
+ *
+ * A pergunta só existe na primeira vez: com a function no ar já com `retry`, ela não volta.
+ */
+export const FAILURE_POLICY_REFUSAL = /Pass the --force option to deploy functions with a failure policy/;
 const TERMINAL_FAILURES = [
     {
         match: /Aborting because deletion cannot proceed in non-interactive mode/,
@@ -74,6 +86,15 @@ const TERMINAL_FAILURES = [
             '  microteia deploy --prune',
         ],
     },
+    {
+        match: FAILURE_POLICY_REFUSAL,
+        hint: [
+            'The function now retries failed deliveries, and the Firebase CLI asks to confirm that once.',
+            'It was not confirmed here because the project may still hold a copy of the function in another',
+            'region, which the same confirmation would delete without asking. Remove old copies first:',
+            '  microteia deploy --prune',
+        ],
+    },
     {
         match: /does not have a default and cannot be answered in non-interactive mode/,
         hint: [
@@ -97,9 +118,9 @@ export const terminalFailure = (output) => {
  * gatilho falha enquanto as callables sobem normalmente. Repetir resolve, e sem isso a primeira
  * instalação parece quebrada quando está apenas incompleta.
  */
-const deployOne = async (name, options) => {
+const deployOne = async (name, options, force = options.force) => {
     const args = ['deploy', '--only', `functions:${name}`, '--project', options.projectId];
-    if (options.force)
+    if (force)
         args.push('--force');
     const startedAt = Date.now();
     const result = await capture(FIREBASE_BIN, args, { cwd: options.cwd });
@@ -111,6 +132,10 @@ const deployOne = async (name, options) => {
         seconds: Math.round((Date.now() - startedAt) / 1000),
     };
 };
+export const mayConfirmRetryPolicy = (name, output, options) => !options.force
+    && options.standingCopies !== null
+    && !options.standingCopies.has(name)
+    && FAILURE_POLICY_REFUSAL.test(stripVTControlCharacters(output));
 export const deployFunctionsOneByOne = async (names, options) => {
     const deployed = [];
     const failed = [];
@@ -134,9 +159,15 @@ export const deployFunctionsOneByOne = async (names, options) => {
             const name = remaining[index];
             const label = `[${index + 1}/${remaining.length}] ${name}`;
             pending(label);
-            const { ok, output, notices: given, seconds } = await deployOne(name, options);
+            let { ok, output, notices: given, seconds } = await deployOne(name, options);
             for (const notice of given)
                 notices.add(notice);
+            if (!ok && mayConfirmRetryPolicy(name, output, options)) {
+                info(`        ${name} now retries failed deliveries, as its source declares: confirming it`);
+                ({ ok, output, notices: given, seconds } = await deployOne(name, options, true));
+                for (const notice of given)
+                    notices.add(notice);
+            }
             if (ok) {
                 success(`${label} (${seconds}s)`);
                 deployed.push(name);

package/lib/console/exportCatalog.d.ts

@@ -98,6 +98,20 @@ export interface CatalogExtensionExportedArtifact {
     kind: 'workflow' | 'action' | 'script' | 'unknown';
     name: string;
 }
+/**
+ * Um grupo da barra lateral que a extensão declara (`ui.nav.group`). Viaja porque a CHAVE é contrato:
+ * é o que outra extensão escreve para entrar no grupo, e quem autora sem enxergá-la inventa outra — e
+ * o menu passa a mostrar dois grupos com o mesmo nome.
+ *
+ * O nome vai resolvido em cada idioma que o próprio pacote traz, porque é pelo nome que o autor
+ * reconhece o grupo; o rótulo literal vai como está, com `translations` vazio.
+ */
+export interface CatalogExtensionNavGroup {
+    key: string;
+    label: string;
+    translations: Record<string, string>;
+    order: number;
+}
 export interface CatalogExtensionExport {
     id: string;
     name: string;
@@ -108,6 +122,8 @@ export interface CatalogExtensionExport {
      * a chave ausente é o silêncio de um Console anterior a este campo, e o kernel distingue as duas.
      */
     exports: CatalogExtensionExportedArtifact[];
+    /** Sempre escrita, mesmo vazia, pela mesma razão de `exports`. */
+    navGroups: CatalogExtensionNavGroup[];
 }
 export interface CatalogExport {
     version: number;

package/lib/console/exportCatalog.js

@@ -78,6 +78,54 @@ const exportedArtifacts = (extension) => {
         .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,
+            }];
+    });
+};
 /**
  * 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 é
@@ -174,6 +222,7 @@ export const buildCatalogExport = (input) => ({
         version: one.version,
         active: one.active,
         exports: exportedArtifacts(one),
+        navGroups: navGroupsOf(one),
     }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
     screens: input.screens
@@ -293,6 +342,8 @@ export const exportCatalog = async (args) => {
         + `the rest the office built itself.`);
     const exported = document.extensions.reduce((total, one) => total + one.exports.length, 0);
     info(`  ${exported} artifact(s) are declared for other extensions to reference as <extension-id>/<id>.`);
+    const groups = document.extensions.reduce((total, one) => total + one.navGroups.length, 0);
+    info(`  ${groups} sidebar group(s) are declared, by key, for other extensions to join.`);
     blank();
     await checkIgnored(directory);
     info('It is a SNAPSHOT, and it says so: the authoring tools report when it was taken and warn when it');

package/lib/console/provision.js

@@ -428,8 +428,8 @@ export const provisionBackend = async (options) => {
         }
         // A extensão que mudou de região deixa a cópia antiga para trás igual ao kernel, e ali o efeito
         // é o mesmo: deploy recusado em toda tentativa, e gatilho disparando em duas regiões.
-        await clearRegionOrphans(projectId, toDeploy, region, options.prune, await projectFunctions());
-        const deployOptions = { projectId, cwd: install, delaySeconds, force: false };
+        const standingCopies = await clearRegionOrphans(projectId, toDeploy, region, options.prune, await projectFunctions());
+        const deployOptions = { projectId, cwd: install, delaySeconds, force: false, standingCopies };
         if (!probing)
             info(`  deploying ${toDeploy.length} function(s), one at a time…`);
         const report = probing

package/lib/console/regionOrphans.d.ts

@@ -50,10 +50,15 @@ export declare const deleteCommand: (projectId: string, orphan: RegionOrphan) =>
  * Avisa por padrão e só apaga com `--prune`, como `settleOrphans` faz com a function que perdeu dono.
  * Apagar uma Cloud Function é irreversível e é do escritório, não nosso: o comando tem de ser pedido.
  */
-export declare const settleRegionOrphans: (projectId: string, orphans: RegionOrphan[], prune: boolean) => Promise<boolean>;
+export declare const settleRegionOrphans: (projectId: string, orphans: RegionOrphan[], prune: boolean) => Promise<ReadonlySet<string>>;
 /**
- * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve `true` quando o caminho está
- * livre — inclusive quando não deu para verificar, pela mesma razão de `listDeployedFunctions`.
+ * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve os nomes cuja cópia antiga
+ * CONTINUA de pé, ou `null` quando não deu para verificar — e não bloqueia o deploy em nenhum dos dois
+ * casos, pela mesma razão de `listDeployedFunctions`.
+ *
+ * O conjunto é o que autoriza o `--force` pontual de `deployFunctionsOneByOne`: com ele o `firebase`
+ * aceita a política de repetição E apaga sem perguntar a cópia de outra região, e essa segunda decisão
+ * é do escritório, pedida com `--prune`. Não saber equivale a ter cópia.
  */
 export declare const clearRegionOrphans: (projectId: string, wanted: string[], region: string, prune: boolean, 
 /**
@@ -61,4 +66,4 @@ export declare const clearRegionOrphans: (projectId: string, wanted: string[], r
  * a mesma coisa ao mesmo projeto não é caro, é ambíguo: as duas respostas podem divergir, e a
  * decisão passa a depender de qual delas o código olhou.
  */
-listed?: DeployedFunction[] | null) => Promise<boolean>;
+listed?: DeployedFunction[] | null) => Promise<ReadonlySet<string> | null>;

package/lib/console/regionOrphans.js

@@ -51,7 +51,7 @@ export const deleteCommand = (projectId, orphan) => `firebase functions:delete $
  */
 export const settleRegionOrphans = async (projectId, orphans, prune) => {
     if (orphans.length === 0)
-        return true;
+        return new Set();
     blank();
     warn(`${orphans.length} function(s) are still deployed in a region this package no longer uses:`);
     bullets(orphans.map((orphan) => `${orphan.name} (${orphan.region})`));
@@ -66,11 +66,11 @@ export const settleRegionOrphans = async (projectId, orphans, prune) => {
         info('  or one at a time:');
         bullets(orphans.map((orphan) => deleteCommand(projectId, orphan)));
         blank();
-        return false;
+        return new Set(orphans.map((orphan) => orphan.name));
     }
     const plural = orphans.length === 1 ? 'copy' : 'copies';
     info(`  --prune: removing the ${orphans.length} old ${plural} before deploying.`);
-    let cleared = true;
+    const standing = new Set();
     for (const orphan of orphans) {
         const label = `${orphan.name} (${orphan.region})`;
         pending(label);
@@ -87,15 +87,20 @@ export const settleRegionOrphans = async (projectId, orphans, prune) => {
             failure(`${label} could not be removed`);
             info(`        ${failureReason(`${result.stdout}${result.stderr}`)}`);
             info(`        ${deleteCommand(projectId, orphan)}`);
-            cleared = false;
+            standing.add(orphan.name);
         }
     }
     blank();
-    return cleared;
+    return standing;
 };
 /**
- * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve `true` quando o caminho está
- * livre — inclusive quando não deu para verificar, pela mesma razão de `listDeployedFunctions`.
+ * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve os nomes cuja cópia antiga
+ * CONTINUA de pé, ou `null` quando não deu para verificar — e não bloqueia o deploy em nenhum dos dois
+ * casos, pela mesma razão de `listDeployedFunctions`.
+ *
+ * O conjunto é o que autoriza o `--force` pontual de `deployFunctionsOneByOne`: com ele o `firebase`
+ * aceita a política de repetição E apaga sem perguntar a cópia de outra região, e essa segunda decisão
+ * é do escritório, pedida com `--prune`. Não saber equivale a ter cópia.
  */
 export const clearRegionOrphans = async (projectId, wanted, region, prune, 
 /**
@@ -106,6 +111,6 @@ export const clearRegionOrphans = async (projectId, wanted, region, prune,
 listed) => {
     const deployed = listed === undefined ? await listDeployedFunctions(projectId) : listed;
     if (deployed === null)
-        return true;
+        return null;
     return settleRegionOrphans(projectId, regionOrphans(deployed, wanted, region), prune);
 };

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.28.0";
+export declare const CLI_VERSION = "2.29.0";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.28.0';
+export const CLI_VERSION = '2.29.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",