@microteia/console 2.7.0 → 2.7.2

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,33 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.7.2] — 2026-08-25
+
+- feat(vendor/exampleSources): stages `automation-example` alongside the others, so the workspace ships a complete automation to read. Every example that travelled carried `workflows: []`, and automation was the one mechanism an author had only prose for.
+
+#### [2.7.1] — 2026-08-24
+
+- fix(unpack): the default catalog URL is `https://microteia.github.io/releases/kernel/index.json`.
+  `2.7.0` shipped pointing at a domain that was never registered, so `--version` on it fails with
+  "Could not read the Microteia catalog" and only `--kernel <package>.tgz` works. The choice of host is
+  not the point; where the INDEX lives is, because that one URL is the only address a Console knows by
+  heart — every other URL is data inside the catalog. A `github.io` address is free, exists today, and
+  is forward compatible: adding a custom domain to the Pages site later makes GitHub redirect the old
+  address to it, and `fetch` follows redirects, so a Console installed now keeps working. Starting at a
+  domain would have required owning it first and offered no way back.
+- fix(publish): a repository with no commits at all is the FIRST publish, not a failure. The contents
+  API answers `404 Not Found` when the file is missing and `404 This repository is empty` when there is
+  no commit — and the second is the state of a releases repository just created, which is exactly when
+  the first publish happens. Matching on the message refused it. A 404 now asks one more question, about
+  the repository itself, which separates "the catalog is not there yet" (go on) from "the repository is
+  not there" (stop) instead of guessing from prose.
+- fix(publish): a releases repository with no commits is seeded before the release is created. GitHub
+  refuses to create a release or a tag in an empty repository with `422 Repository is empty`, and it
+  refuses it AFTER the package has been verified — the worst moment to find out. The first publish now
+  writes the repository's `README.md`, which is a write the command was going to make three steps later
+  anyway, and which the repository should carry regardless. It is written once and never overwritten:
+  what promises to be current is the catalog.
+
 #### [2.7.0] — 2026-08-24
 
 - feat(unpack): `--version latest` and `--version <x.y.z>` take a platform version from the published

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.7.0
+# Microteia Console 2.7.2
 
 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/channel.d.ts

@@ -16,7 +16,7 @@ import type { ChannelEntry, ChannelIndex } from '../kernel/channel.js';
  * mudar de hospedagem — ou passar a emitir URL assinada por escritório, que o host de hoje não faz —
  * reescreve o índice, e um Console já instalado continua achando o catálogo no mesmo lugar.
  */
-export declare const DEFAULT_INDEX_URL = "https://dist.microteia.app/kernel/index.json";
+export declare const DEFAULT_INDEX_URL = "https://microteia.github.io/releases/kernel/index.json";
 export declare const indexUrl: () => string;
 /**
  * O cache fica FORA da instalação, de propósito: `.microteia/` é apagado por inteiro a cada troca de

package/lib/console/channel.js

@@ -22,7 +22,7 @@ import { LATEST, kernelTarballName, parseIndex, resolveVersion } from '../kernel
  * mudar de hospedagem — ou passar a emitir URL assinada por escritório, que o host de hoje não faz —
  * reescreve o índice, e um Console já instalado continua achando o catálogo no mesmo lugar.
  */
-export const DEFAULT_INDEX_URL = 'https://dist.microteia.app/kernel/index.json';
+export const DEFAULT_INDEX_URL = 'https://microteia.github.io/releases/kernel/index.json';
 export const indexUrl = () => {
     const override = process.env.MICROTEIA_INDEX_URL;
     return override === undefined || override === '' ? DEFAULT_INDEX_URL : override;

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.7.0";
+export declare const CLI_VERSION = "2.7.2";

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.7.0';
+export const CLI_VERSION = '2.7.2';

package/lib/vendor/exampleSources.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
  */
 /** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
 export const EXAMPLE_SOURCES = {
+    'automation-example': 'automation.ts',
     brasil: 'brasil.ts',
     calendar: 'calendar.ts',
     dashboard: 'dashboard.ts',

package/lib/vendor/publish.js

@@ -42,24 +42,75 @@ const exists = async (path) => {
     }
 };
 const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
-/**
- * Lê o catálogo pela API de conteúdo, e não pela URL pública: o que interessa é o que está no
- * repositório AGORA, e o Pages serve de um cache que pode estar minutos atrás. Publicar contra a
- * versão em cache perderia a entrada de quem publicou antes.
- */
 const readPublishedIndex = async (repo) => {
     const result = await capture('gh', ['api', `repos/${repo}/contents/${INDEX_PATH}`]);
     if (result.code !== 0) {
-        if (result.stderr.includes('Not Found') || result.stdout.includes('Not Found')) {
+        const detail = `${result.stderr}${result.stdout}`;
+        /**
+         * Um 404 aqui tem DUAS causas, e elas pedem coisas opostas: o catálogo ainda não existe (primeira
+         * publicação, segue em frente) ou o repositório não existe (erro de nome, pare). Distinguir por
+         * texto não serve — a API responde "Not Found" quando falta o arquivo e "This repository is empty"
+         * quando o repositório não tem commit nenhum, que é o caso de um repo recém-criado e é exatamente
+         * quando a primeira publicação acontece.
+         *
+         * Então quem distingue é uma pergunta a mais, sobre o repositório em si. Ela custa uma chamada e
+         * remove a ambiguidade inteira.
+         */
+        if (detail.includes('HTTP 404')) {
+            const repository = await capture('gh', ['api', `repos/${repo}`]);
+            if (repository.code !== 0) {
+                throw new Error(`The repository ${repo} could not be read.\n${repository.stderr.trim() || repository.stdout.trim()}\n`
+                    + 'Check the name, and that "gh auth status" reports an account with access to it.');
+            }
             info(`  ${INDEX_PATH} does not exist in ${repo} yet — this is the first published version`);
-            return { index: emptyIndex(), sha: null };
+            return { index: emptyIndex(), sha: null, empty: detail.includes('repository is empty') };
         }
         throw new Error(`Could not read ${INDEX_PATH} from ${repo}.\n${result.stderr.trim() || result.stdout.trim()}\n`
             + 'Is "gh" authenticated (gh auth status) and does the repository exist?');
     }
     const contents = JSON.parse(result.stdout);
     const text = Buffer.from(contents.content, 'base64').toString('utf8');
-    return { index: parseIndex(text, `${repo}/${INDEX_PATH}`), sha: contents.sha };
+    return { index: parseIndex(text, `${repo}/${INDEX_PATH}`), sha: contents.sha, empty: false };
+};
+/**
+ * O que fica na raiz do repositório de releases, para quem chegar nele sem contexto.
+ *
+ * Ele é escrito UMA vez, ao semear — não é sobreposto depois. O que promete estar atual é o catálogo,
+ * e é ele que a cada publicação é reescrito.
+ */
+const releasesReadme = () => `# Microteia — releases
+
+Distribution artifacts for the Microteia platform. **No source lives here**: what travels is compiled.
+
+- \`kernel/index.json\` — the catalog the Microteia Console reads. It lists every published version with
+  its size and sha256, and the absolute URLs of the files that carry it.
+- Each version is a release tagged \`kernel-<version>\`, carrying the package and its manifest.
+
+Nobody downloads from here by hand:
+
+    npm i -g @microteia/console
+    microteia unpack --version latest
+
+The Console reads the catalog, verifies what it downloads against the sha256 above, and only then puts
+it in place.
+`;
+/**
+ * Dá ao repositório o primeiro commit, porque sem ele não existe release.
+ *
+ * Um repositório de releases recém-criado está vazio, e o GitHub recusa criar release ou tag ali com
+ * `422 Repository is empty` — depois de o pacote já ter sido conferido, que é o pior momento para
+ * descobrir. Semear é uma escrita que este comando ia fazer de qualquer forma três passos adiante; ela
+ * só passou a acontecer antes, e traz junto o README que o repositório precisa ter.
+ */
+const seedRepository = async (repo) => {
+    pending(`${repo} has no commits yet — writing its README first`);
+    const content = Buffer.from(releasesReadme(), 'utf8').toString('base64');
+    await captureOrThrow('gh', [
+        'api', '--method', 'PUT', `repos/${repo}/contents/README.md`,
+        '-f', 'message=the releases repository',
+        '-f', `content=${content}`,
+    ]);
+    success(`seeded ${repo}`);
 };
 const writePublishedIndex = async (repo, index, sha, version) => {
     const content = Buffer.from(serializeIndex(index), 'utf8').toString('base64');
@@ -134,9 +185,13 @@ const publishKernel = async (root, version, repo, dryRun) => {
     success(`kernel ${version} verified: ${manifest.tarball?.bytes} bytes, sha256 ${manifest.tarball?.sha256.slice(0, 12)}…`);
     info(`  tag ${tagOf(version)} in ${repo}, and ${INDEX_PATH} promoting it to "latest"`);
     if (dryRun) {
+        if (published.empty)
+            info(`  ${repo} has no commits, so it would be seeded with a README first`);
         info(`  the catalog would go from ${published.index.kernel.length} to ${next.kernel.length} version(s)`);
         return;
     }
+    if (published.empty)
+        await seedRepository(repo);
     const notes = await mkdtemp(join(tmpdir(), 'microteia-publish-'));
     const notesFile = join(notes, 'notes.md');
     await writeFile(notesFile, entry);

package/package.json

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