@microteia/console 2.42.0 → 2.43.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,18 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.43.0] — 2026-11-10
+
+- feat(plugin-init): with a terminal, asks the publisher and the prefix right after the namespace, each
+  with a short explanation, and records them in the seed `package.json` under `microteia.publisher` and
+  `microteia.prefix` — the keys `microteia-plugin create` reads. The publisher suggests the office name
+  (`project.name` in `microteia.yaml`); the prefix suggests the one `create` would (the namespace's last
+  segment when it fits, `com.acme` → `acme`); Enter accepts either. Until now both were asked by the first
+  `create`, so a value that never changes was chosen by whoever ran the first extension — often an agent.
+- feat(plugin-init): `--publisher <name>` and `--prefix <acme>` answer without a terminal; an invalid
+  prefix is refused before anything is written. Without a terminal and without the flags, both are left
+  out and `create` asks for them once, as before. `--force` reuses the three values already recorded.
+
 #### [2.42.0] — 2026-11-08
 
 - feat(kernel/manifest)!: the optional prerequisite `self-service-tenants` and the backend parameter

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.42.0
+# Microteia Console 2.43.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/pluginWorkspace.js

@@ -6,7 +6,7 @@ import { blank, bullets, heading, info, success, warn } from '../shared/ui.js';
 import { run } from '../shared/run.js';
 import { ENVIRONMENT_FILE, readEnvironment } from './environment.js';
 import { WORKSPACE_DIR } from './workspace.js';
-import { SDK_TARBALL, isValidNamespace, workspacePackageJson } from '../vendor/pluginWorkspaceTemplates.js';
+import { SDK_TARBALL, isValidNamespace, isValidPrefix, suggestPrefix, workspacePackageJson, } from '../vendor/pluginWorkspaceTemplates.js';
 /**
  * `microteia plugin-init` — prepara `extensions/`, onde o escritório escreve extensão em TypeScript.
  *
@@ -108,40 +108,100 @@ export const refreshAuthoringWorkspace = async (root, officeName) => {
         return false;
     }
 };
-/** O que um `--force` anterior deixou gravado: reescrever a semente não é motivo para perguntar de novo. */
-const existingNamespace = async (directory) => {
+/**
+ * O que um `--force` anterior deixou gravado: reescrever a semente não é motivo para perguntar de novo —
+ * e o prefixo, uma vez usado, não pode mudar.
+ */
+const existingIdentity = async (directory) => {
     try {
         const pkg = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
-        const value = pkg.microteia?.namespace;
-        return typeof value === 'string' && isValidNamespace(value) ? value : null;
+        const { namespace, publisher, prefix } = pkg.microteia ?? {};
+        return {
+            ...(typeof namespace === 'string' && isValidNamespace(namespace) ? { namespace } : {}),
+            ...(typeof publisher === 'string' && publisher.trim() !== '' ? { publisher: publisher.trim() } : {}),
+            ...(typeof prefix === 'string' && isValidPrefix(prefix) ? { prefix } : {}),
+        };
     }
     catch {
-        return null;
+        return {};
     }
 };
+const invalidNamespace = (namespace) => new Error(`"${namespace}" is not a valid namespace. Use reverse-DNS, lowercase, from a domain your organization`
+    + ' controls — for example: --namespace com.acme');
+const invalidPrefix = (prefix) => new Error(`"${prefix}" is not a valid prefix. Use 2 to 8 lowercase letters or digits, starting with a letter`
+    + ' — for example: --prefix acme');
+/** Com sugestão, Enter a aceita — é o que torna a sugestão uma resposta, e não só um exemplo. */
+const asker = (rl) => async (label, suggestion) => {
+    const answer = (await rl.question(suggestion === undefined ? `${label}: ` : `${label} [${suggestion}]: `)).trim();
+    return answer === '' && suggestion !== undefined ? suggestion : answer;
+};
 /**
- * O namespace é OBRIGATÓRIO, e não tem padrão: qualquer padrão seria um prefixo que não é do escritório,
- * e o id que nasce dele é permanente. Sem terminal, só a flag responde.
+ * Namespace, publisher e prefix — os três valem para TODA extensão do diretório, e por isso são
+ * perguntados aqui, uma vez, e não no primeiro `create`: quem chegava a ele de um agente via o prefixo
+ * ser escolhido por quem não podia escolhê-lo.
+ *
+ * O namespace é OBRIGATÓRIO e não tem padrão: qualquer padrão seria um prefixo que não é do escritório,
+ * e o id que nasce dele é permanente. Sem terminal, só a flag o responde. Publisher e prefix, sem
+ * terminal e sem flag, ficam para o `create` — que já sabe perguntá-los.
  */
-const resolveNamespace = async (args, directory) => {
-    const given = flagValue(args, 'namespace') ?? await existingNamespace(directory) ?? await askNamespace();
-    const namespace = given.trim();
-    if (!isValidNamespace(namespace)) {
-        throw new Error(`"${namespace}" is not a valid namespace. Use reverse-DNS, lowercase, from a domain your organization`
-            + ' controls — for example: --namespace com.acme');
-    }
-    return namespace;
-};
-const askNamespace = async () => {
+const resolveIdentity = async (args, directory, officeName) => {
+    const stored = await existingIdentity(directory);
+    const given = {
+        namespace: flagValue(args, 'namespace')?.trim() ?? stored.namespace,
+        publisher: flagValue(args, 'publisher')?.trim() ?? stored.publisher,
+        prefix: flagValue(args, 'prefix')?.trim() ?? stored.prefix,
+    };
+    if (given.namespace !== undefined && !isValidNamespace(given.namespace))
+        throw invalidNamespace(given.namespace);
+    if (given.prefix !== undefined && !isValidPrefix(given.prefix))
+        throw invalidPrefix(given.prefix);
+    if (given.publisher === '')
+        throw new Error('The publisher cannot be empty — for example: --publisher "Acme Legal"');
     if (!process.stdin.isTTY) {
-        throw new Error('A namespace is required: every extension written in this directory is named below it, and its ids\n'
-            + 'are permanent. Pass it with --namespace, for example: microteia plugin-init --namespace com.acme');
+        if (given.namespace === undefined) {
+            throw new Error('A namespace is required: every extension written in this directory is named below it, and its ids\n'
+                + 'are permanent. Pass it with --namespace, for example: microteia plugin-init --namespace com.acme');
+        }
+        return { namespace: given.namespace, publisher: given.publisher, prefix: given.prefix };
+    }
+    if (given.namespace !== undefined && given.publisher !== undefined && given.prefix !== undefined) {
+        return { namespace: given.namespace, publisher: given.publisher, prefix: given.prefix };
     }
-    info('Every extension written here is named below a namespace — the reverse-DNS of a domain your');
-    info('organization controls, like com.acme. Its ids are permanent, so choose one that is yours.');
     const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = asker(rl);
     try {
-        return (await rl.question('namespace: ')).trim();
+        let namespace = given.namespace;
+        if (namespace === undefined) {
+            blank();
+            info('NAMESPACE — every extension written here is named below it: "billing" becomes com.acme.billing.');
+            info('Use the reverse-DNS of a domain your organization controls. The ids are permanent, so choose one');
+            info('that is yours.');
+            namespace = await ask('namespace');
+            if (!isValidNamespace(namespace))
+                throw invalidNamespace(namespace);
+        }
+        let publisher = given.publisher;
+        if (publisher === undefined) {
+            blank();
+            info('PUBLISHER — who answers for these extensions. It is shown as the author of each one on the');
+            info('Extensions screen of every office that installs it. A name, not an id.');
+            publisher = await ask('publisher', officeName);
+            if (publisher === '')
+                throw new Error('The publisher cannot be empty.');
+        }
+        let prefix = given.prefix;
+        if (prefix === undefined) {
+            blank();
+            info('PREFIX — starts every name your extensions create: acme_clients for a collection, acme-notify for');
+            info('an automation. It keeps two publishers who both pick "clients" from colliding in the same office.');
+            info('2 to 8 lowercase letters or digits. It never changes: a new prefix would rename the collections');
+            info('and leave their records behind. The suggestion comes from the namespace.');
+            prefix = await ask('prefix', suggestPrefix(namespace));
+            if (!isValidPrefix(prefix))
+                throw invalidPrefix(prefix);
+        }
+        blank();
+        return { namespace, publisher, prefix };
     }
     finally {
         rl.close();
@@ -160,19 +220,25 @@ export const pluginInit = async (args) => {
     }
     const sdk = await locateSdk(root);
     const installDir = join(root, WORKSPACE_DIR, 'install');
-    const namespace = await resolveNamespace(args, directory);
     heading(`Extension authoring for "${environment.project.name}"`);
+    const identity = await resolveIdentity(args, directory, environment.project.name);
+    const { namespace } = identity;
     await mkdir(directory, { recursive: true });
     // O caminho do tarball é relativo, para que o diretório continue válido se a instalação inteira for
     // movida — o que acontece assim que alguém a versiona num repositório do escritório.
-    await writeFile(join(directory, 'package.json'), workspacePackageJson(environment.environment.id, relative(directory, sdk.path), namespace));
-    success(`wrote the seed package.json (namespace ${namespace})`);
+    await writeFile(join(directory, 'package.json'), workspacePackageJson(environment.environment.id, relative(directory, sdk.path), identity));
+    success(`wrote the seed package.json (namespace ${namespace}`
+        + `${identity.publisher === undefined ? '' : `, publisher "${identity.publisher}"`}`
+        + `${identity.prefix === undefined ? '' : `, prefix ${identity.prefix}`})`);
+    if (identity.publisher === undefined || identity.prefix === undefined) {
+        info('  publisher and prefix not given — "npm run create" asks for them once, and records them there.');
+    }
     blank();
     info('Installing @microteia/sdk and writing the guides...');
     await syncAuthoringWorkspace(directory, sdk.path, installDir, environment.project.name);
     blank();
     info(`Extension authoring ready in ${relative(root, directory)}/ (kernel contract ${sdk.kernelVersion}).`);
-    info(`Every extension created there is ${namespace}.<name> — recorded in package.json, under microteia.namespace.`);
+    info(`Every extension created there is ${namespace}.<name> — recorded in package.json, under microteia.`);
     bullets([
         `cd ${relative(process.cwd(), directory) || '.'}`,
         'npm run create',

package/lib/index.js

@@ -67,7 +67,7 @@ const COMMANDS = [
     },
     {
         name: 'plugin-init',
-        usage: 'microteia plugin-init --namespace <com.acme> [--dir <path>] [--force]',
+        usage: 'microteia plugin-init --namespace <com.acme> [--publisher <name>] [--prefix <acme>] [--dir <path>] [--force]',
         summary: 'Prepare "extensions/", to author extensions in TypeScript in your editor.',
         audience: 'office',
         execute: pluginInit,

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.42.0";
+export declare const CLI_VERSION = "2.43.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.42.0';
+export const CLI_VERSION = '2.43.0';

package/lib/vendor/pluginWorkspaceTemplates.d.ts

@@ -16,5 +16,22 @@ export declare const SDK_TARBALL = "microteia-sdk.tgz";
  * 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, namespace: string) => string;
+/**
+ * O que só quem roda o `plugin-init` pode decidir, e que vale para TODA extensão do diretório. O
+ * `publisher` e o `prefix` são opcionais: sem terminal e sem flag, quem os pergunta é o `create` do SDK,
+ * uma vez — o mesmo que faz num diretório anterior a eles.
+ */
+export interface WorkspaceIdentity {
+    namespace: string;
+    publisher?: string;
+    prefix?: string;
+}
+export declare const workspacePackageJson: (officeName: string, sdkPath: string, identity: WorkspaceIdentity) => string;
 export declare const isValidNamespace: (value: string) => boolean;
+export declare const isValidPrefix: (value: string) => boolean;
+/**
+ * A sugestão do `create` do SDK (`suggestedPrefix`), repetida aqui para que o `plugin-init` ofereça o
+ * MESMO prefixo que o `create` ofereceria: o último segmento do namespace, se ele já serve
+ * (`com.acme` → `acme`), senão os primeiros caracteres que servem, senão quatro letras sorteadas.
+ */
+export declare const suggestPrefix: (namespace: string, random?: () => number) => string;

package/lib/vendor/pluginWorkspaceTemplates.js

@@ -11,12 +11,7 @@
  * escritório. É a semente — mínima de propósito, porque quem a completa é o `sync`.
  */
 export 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 const workspacePackageJson = (officeName, sdkPath, namespace) => JSON.stringify({
+export const workspacePackageJson = (officeName, sdkPath, identity) => JSON.stringify({
     name: `${officeName}-extensions`,
     version: '0.0.0',
     private: true,
@@ -26,9 +21,14 @@ export const workspacePackageJson = (officeName, sdkPath, namespace) => JSON.str
         // traz o SDK novo é `npm run sdk:refresh` — ou o `microteia unpack`, que o faz sozinho.
         '@microteia/sdk': `file:${sdkPath}`,
     },
-    // O prefixo de todo id escrito neste diretório. É o SDK que o lê (`microteia-plugin create`, o MCP);
-    // o Console só o recebe de quem roda o `plugin-init`, que é a única pessoa que pode decidi-lo.
-    microteia: { namespace },
+    // É o SDK que lê estas chaves (`microteia-plugin create`, o MCP); o Console só as recebe de quem roda
+    // o `plugin-init`, que é a única pessoa que pode decidi-las. Chave sem valor fica de fora, e não
+    // vazia: o `create` só pergunta o que não acha.
+    microteia: {
+        namespace: identity.namespace,
+        ...(identity.publisher === undefined ? {} : { publisher: identity.publisher }),
+        ...(identity.prefix === undefined ? {} : { prefix: identity.prefix }),
+    },
 }, null, 2) + '\n';
 /**
  * O formato de id de extensão (`isValidPluginId`, no domínio) — repetido porque o Console não importa
@@ -37,3 +37,24 @@ export const workspacePackageJson = (officeName, sdkPath, namespace) => JSON.str
  */
 const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
 export const isValidNamespace = (value) => NAMESPACE_PATTERN.test(value);
+/**
+ * O formato do prefixo de artefato (`ARTIFACT_PREFIX_PATTERN`, no domínio) — repetido pela mesma razão do
+ * namespace, e preso a ele pelo mesmo teste.
+ */
+const PREFIX_PATTERN = /^[a-z][a-z0-9]{1,7}$/;
+const PREFIX_MAX_LENGTH = 8;
+const GENERATED_PREFIX_LENGTH = 4;
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
+export const isValidPrefix = (value) => PREFIX_PATTERN.test(value);
+/**
+ * A sugestão do `create` do SDK (`suggestedPrefix`), repetida aqui para que o `plugin-init` ofereça o
+ * MESMO prefixo que o `create` ofereceria: o último segmento do namespace, se ele já serve
+ * (`com.acme` → `acme`), senão os primeiros caracteres que servem, senão quatro letras sorteadas.
+ */
+export const suggestPrefix = (namespace, random = Math.random) => {
+    const last = (namespace.split('.').pop() ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    const candidate = last.replace(/^[0-9]+/, '').slice(0, PREFIX_MAX_LENGTH);
+    if (isValidPrefix(candidate))
+        return candidate;
+    return Array.from({ length: GENERATED_PREFIX_LENGTH }, () => LETTERS[Math.floor(random() * LETTERS.length) % LETTERS.length]).join('');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "AGPL-3.0-or-later",
   "repository": {