cms: store ID and published schema versions are undiscoverable, and guessing fails silently

[JonasJesus42]

Context

Migrating cuida.electrolux.com.ec into the Electrolux FastStore storefront. Before authoring
entries with parity cms, we needed two values. Neither is discoverable today, and both fail
silently when wrong.

Problem 1 — the store ID is unguessable, and a wrong one looks valid

parity cms requires PARITY_CMS_STORE, but nothing tells you what it is. On this account three
independently plausible values were all wrong:

Candidate	Why it looked right	Result
faststore	the repo has cms/faststore/, @faststore/core ships cms/faststore/, and vtex content upload-schema defaults to it	wrong
electroluxecfaststore	the VTEX account, and what discovery.config.js calls storeId	wrong
electroluxec	a sibling VTEX account	wrong (401 — different account)

The real value is electrolux, which matches nothing in the repo.

What makes this expensive is that a wrong store ID does not error:

GET api/content-platform/manage/{account}/{anything}/branches   -> 200 []
GET api/content-platform/schemas/{account}.{anything}/content-types -> 404 SCHEMA_NOT_FOUND

200 [] for any string reads as "valid store, no branches yet". Accepting the CLI default would
have published a schema into a namespace nothing reads — sections present in the registry, absent
from the CMS, and no error anywhere.

The one reliable way we found (note it does not take a store, so it bootstraps):

GET api/content-platform/manage/{account}/entries?contentTypes=&page=1&pageSize=100
-> { entries: [ { storeId: "electrolux", contentTypeId: "landingPage", ... } ] }

Problem 2 — published schema versions cannot be listed

vtex content upload-schema prompts for a semver and rejects one already in the registry:

? Schema version to publish (e.g. 1.2.0 or 1.2.0-beta.1, not already in the registry)
> Version must be major.minor.patch, optionally with a prerelease tag

But there is no way to see what is already published:

• vtex content only has generate-schema, init, split-components, split-content-types, upload-schema — no list.
• The repo records no schema version; package.json version is the app release, a different thing.
• We could not find a read endpoint for registry versions.

So the only ways forward are asking whoever published last, or guessing a number and hoping it
collides rather than lands somewhere wrong.

Proposal

1. parity cms doctor should resolve and print the store ID from entries[].storeId, and fail
   loudly when PARITY_CMS_STORE disagrees with what the account actually uses. This is the check
   that catches the silent-namespace failure.
2. Consider making PARITY_CMS_STORE optional, deriving it when unambiguous.
3. Investigate whether the schema registry exposes published versions. If it does, surface them
   in doctor and suggest the next version on upload. If it does not, that is worth documenting so
   people stop looking.

Both are prerequisites to a safe first publish, and today both are guesswork.

[JonasJesus42]

Correcting myself on Problem 2 — I was wrong, and I'd rather say so before someone spends time
building what already exists.

Published versions are discoverable. upload-schema --yes prints them:

info - Latest published version for electroluxecfaststore.electrolux: 1.3.0.
info - Suggested next version (minor bump): 1.4.0.
info - Using version 1.4.0 (--yes).

So the CLI already knows the latest and already computes the next bump. What tripped me up is that
this only surfaces as a side effect of --yes — without it, the prompt asks for a version and
tells you it must not already be in the registry, while never saying what is. Reduced scope: show
the latest published version in the interactive prompt too, so the default is visible before you
commit to it.

Also worth noting for whoever picks this up: --account, --storeId and --yes all exist on
upload-schema but are hidden: true, so --help lists only -h, -v and --trace. I only
found them by reading build/commands/content/upload-schema.js. Hiding the two flags that prevent
the wrong-store failure below seems backwards.

Problem 1 stands unchanged, and is the one that matters. The prompt defaults to faststore,
the real store was electrolux, and the wrong value fails silently — manage/{account}/{anything}/branches
answers 200 [] for any string at all. Publishing there would have put the schema in a namespace
nothing reads, with no error at any point.

Related: #325 corrects a comment in commitEntry claiming a new entry is the same call with an
unused entryId. It isn't — that path answers 404 ENTRY_NOT_FOUND, so pages still have to be
created once in the Admin before parity cms can drive them.

[JonasJesus42]

Confirmado de novo hoje (2026-09-03), publicando o schema do Cuida no mesmo account. Dois dados novos que fecham as duas metades desta issue:

Problema 2 tem solução simples. O mesmo endpoint de schemas sem a versão devolve a versão corrente no $id:

GET https://{account}.myvtex.com/api/content-platform/schemas/{account}.{store}
-> { "$id": "electroluxecfaststore.electrolux@1.5.0", ... }

Isso é tudo que upload-schema precisa para sugerir o próximo semver — dá para parity expor como parity cms schema version ou simplesmente calcular o bump sozinho.

Um agravante novo: o prompt não é automatizável. vtex content upload-schema não tem flag nenhuma (só -h, -v, --trace), então todo valor vem de prompt. E automatizar com expect + exp_continue entra em loop infinito: o prompt do oclif continua no buffer depois de respondido e re-casa o padrão, então o script fica digitando a mesma resposta para sempre (peguei ~4000 repetições de 1.6.0 antes de matar). Só funciona com expect sequencial, um expect/send por prompt, na ordem exata:

1. store ID you want → electrolux
2. Schema version to publish → 1.6.0
3. Are you sure you want to upload → y
4. can be safely deleted ... Delete it? → y

O passo 4 é uma pegadinha à parte: o default é Y e ele apaga cms/faststore/schema.json do disco depois do upload.

Sequência que funcionou, para referência:

set timeout 120
spawn -noecho vtex content upload-schema cms/faststore/schema.json
expect -re "store ID you want";        send "electrolux\r"
expect -re "Schema version to publish"; send "1.6.0\r"
expect { -re "Are you sure" { send "y\r"; exp_continue } eof }

Reforça o pedido do final da issue: isso devia ser parity cms schema push, não expect em cima de um CLI interativo.