@ceupay/template-cli 0.0.0-stage → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.1.0-alpha.3
+
+Add start/serve, hidden short-lived editor session input, isolated interactive
+browser preview with automatic reload, and explicit --watch --yes synchronization.
+Preserve immutable operation files and stop on conflicts or uncertain responses.
+Generate AGENTS.md, CLAUDE.md and complete local Liquid references for new projects.
+Published alpha.2 and private alpha.1 artifacts remain immutable.
+
+## 0.1.0-alpha.2
+
+Add an explicit proprietary use license allowing npm/npx installation and
+AI-assisted customization of authorized CeuPay stores, including commercial
+client work. Preserve ownership of original merchant content and third-party
+license permissions. Include and verify the exact license in the packed artifact.
+
+Prepare the first public npm distribution under `@ceupay`, with explicit public
+access and the `alpha` distribution tag. The standalone CLI includes third-party
+license notices. Local editing and guarded remote publication remain unchanged.
+
+Prévias opcionais de catálogo, produto e post por `--page`, com contexto fictício e validação das páginas permitidas. O formato JSON existente preserva esses arquivos. Apresentação pública depende de piloto separado, ainda desativado.
+
+Fluxo remoto do piloto: baixar template e histórico, preparar operação persistente, publicar/restaurar com confirmação explícita e recuperar resposta perdida. Vínculo com loja/origem e revisão protege o projeto; credenciais ficam no ambiente. Piloto desativado, alpha ainda não publicada.
+
+## 0.1.0-alpha.1
+
+Primeira alpha local: projetos dos modelos existentes, importação/exportação JSON, validação sem truncamento silencioso e prévia com catálogo fictício. Reutiliza os validadores e sanitizadores canônicos.
+
+Não publicada. Download da loja, publicação remota e histórico/restauração seguem pendentes.

package/LICENSE

@@ -0,0 +1,79 @@
+CeuPay Editor Proprietary Use License
+Version 1.0 — 2026-10-29
+
+Copyright (c) 2026 the CeuPay Editor rights holders. All rights reserved except
+for the permissions expressly granted below.
+
+1. Scope
+
+This license applies to the CeuPay-owned code in @ceupay/template-cli, including
+its editor, validators and bundled CeuPay rendering code (the "Editor"). It does
+not license the CeuPay platform, backend, website, API service, trademarks or any
+other repository code. Third-party components are addressed in section 5.
+
+2. Permitted use
+
+You may download, install, run and make reasonable working or backup copies of
+the Editor, including through npm or npx, to create, inspect, edit, validate,
+preview, import, export and publish templates for CeuPay stores you own or are
+authorized to manage. This permission includes commercial stores and paid design
+or development work for authorized CeuPay customers. No separate Editor license
+fee is required under this license; use of CeuPay services may require a plan.
+
+You may use coding assistants, including Claude, Codex and other AI tools, to
+perform that permitted work. You may provide them the documentation, template
+files and Editor material reasonably needed for that work, subject to your own
+authorization to share those materials. This permission does not authorize
+disclosing store credentials, customer data or other confidential information.
+
+You may inspect the Editor and make local adaptations needed for this permitted
+use. You may not distribute those adaptations as a modified Editor without
+separate written permission from its rights holders.
+
+3. Your templates and other content
+
+This license does not transfer ownership of the templates, HTML, CSS, JavaScript,
+text or other original content you create. You may use, modify, sell and share
+your own template work, including work created with AI assistance, subject to
+rights in any pre-existing material it contains. Bundled CeuPay template examples
+may be used and adapted as part of templates for CeuPay stores under section 2.
+Generating or exporting a template does not transfer ownership of the Editor.
+
+4. Reserved rights
+
+Except as expressly permitted above or required by applicable law, you may not
+redistribute, relicense, sublicense, sell or publish copies of the Editor or
+modified versions of it; remove its copyright or license notices; or use its
+code to build or operate a separate editor, competing platform or general-purpose
+template service. You may link others to the official package distribution.
+Public availability on npm does not make this Editor open-source software or
+grant a license to other CeuPay systems. No trademark rights are granted.
+
+5. Third-party software
+
+Third-party components retain their own licenses, notices and permissions.
+See dist/third-party-notices.txt and the licenses supplied with any separately
+installed dependencies. Nothing in this license restricts rights granted by
+those third-party licenses. Its restrictions apply only to CeuPay-owned code.
+
+6. Service authorization
+
+This license does not grant access to a store, account or API. Remote operations
+require the relevant owner's authorization and valid CeuPay access permissions.
+It does not waive service terms or authorize bypassing authentication, store
+isolation, payment validation, plan limits or publication controls.
+
+7. Warranty and liability
+
+To the extent permitted by applicable law, the Editor is provided "AS IS",
+without warranties of merchantability, fitness for a particular purpose or
+non-infringement. Its rights holders are not liable for indirect or consequential
+loss arising from its use. Nothing here excludes rights or liabilities that
+cannot lawfully be excluded.
+
+8. Compliance
+
+The permissions in this license are conditional on compliance with it. If you
+use or distribute the Editor outside these permissions, stop that unauthorized
+use and distribution. Other permissions require separate written authorization
+from the CeuPay Editor rights holders through the official CeuPay support channel.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CLI de templates CeuPay
+
+## Editor com Claude/Codex
+
+No painel Templates, crie uma sessão de 24 horas e copie o segredo. Requer loja
+habilitada e recursos templates/API no plano. Execute:
+
+```sh
+npx @ceupay/template-cli@alpha start ./minha-loja --watch --yes
+```
+
+Cole a sessão na entrada oculta do terminal. Ela só fica na memória do processo;
+nunca passe o segredo como argumento. Em automação confiável, CEUPAY_EDITOR_TOKEN
+substitui a entrada interativa. Revogue a sessão no painel ao terminar, ou em Chaves
+de API após fechar a tela; o prazo máximo é 24 horas, sem rotação para ampliá-lo.
+
+start baixa a loja em uma pasta nova, ou usa um projeto previamente baixado. Abra
+a pasta no Claude/Codex; AGENTS.md, CLAUDE.md e CEUPAY-REFERENCE.md são gerados em
+projetos novos. O endereço 127.0.0.1 exibido abre a prévia com catálogo fictício,
+scripts isolados em iframe e navegação/carrinho simulados. Sem pagamentos reais.
+
+--watch --yes autoriza publicar alterações válidas e estáveis ao salvar. Sem essas
+opções, start apenas baixa/mostra o projeto. serve PASTA mostra um projeto local
+sem sessão remota. Ctrl+C encerra. A prévia recarrega quando arquivos válidos mudam.
+
+Conflito, sessão expirada/revogada ou resposta incerta interrompem sincronização.
+Preserve .ceupay-operations, seus corpos e recibos. Recupere a mesma operação com
+replay e baixe uma pasta nova antes de reaplicar edições. Não apague operações
+para forçar reenvio. Não existe escrita por HTTP no servidor local.
+
+Alpha da etapa 7. Cria projetos editáveis, importa/exporta o JSON existente, valida arquivos e gera prévia local. O fluxo remoto exige habilitação explícita da loja e acesso à API. Novas publicações de código e restaurações exigem o recurso templates.
+
+Distribuição pública alpha:
+
+```sh
+npm install --global @ceupay/template-cli@alpha
+ceupay-template --help
+```
+
+Pacote instalável disponível na [release privada tools-v0.1.0-alpha.1](https://github.com/ceu-studio/store/releases/tag/tools-v0.1.0-alpha.1).
+Baixe `ceupay-template-cli-0.1.0-alpha.1.tgz` e `SHA256SUMS`, confira o SHA-256 e instale:
+
+```sh
+npm install ./ceupay-template-cli-0.1.0-alpha.1.tgz
+npx ceupay-template --help
+```
+
+O download exige acesso ao repositório privado. Comandos locais não exigem credenciais de provedores.
+A alpha.2 usa distribuição pública no npm; a alpha.1 privada é preservada.
+
+## Licença
+
+O editor é proprietário. A [licença de uso](LICENSE) permite instalar e executar
+o pacote por npm/npx e usar Claude, Codex ou outras ferramentas para personalizar
+lojas CeuPay próprias ou de clientes que autorizaram o trabalho, inclusive comercialmente.
+Você mantém os direitos sobre seu conteúdo original. A licença não permite
+redistribuir o editor ou criar outra plataforma com o código dele. Componentes
+de terceiros mantêm suas respectivas licenças em `dist/third-party-notices.txt`.
+
+## Preparar
+
+Requer Node 22.12 ou superior e pnpm 8.15.9. No repositório:
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm build
+pnpm test:types
+pnpm test
+pnpm pack --pack-destination .runtime/dist
+pnpm check:package
+```
+
+O build reutiliza os validadores do site/backend e o renderizador Liquid/HTML/CSS existente. O arquivo `dist/main.cjs` já inclui as dependências necessárias, com seus avisos em `dist/third-party-notices.txt`. A CLI não altera as dependências do site/backend.
+
+Os testes HTTPS exigem OpenSSL. No Windows, `CEUPAY_TEST_OPENSSL` pode indicar o executável instalado.
+
+## Criar e editar
+
+```sh
+node dist/main.cjs bases
+node dist/main.cjs init fogueira ./meu-template
+node dist/main.cjs validate ./meu-template
+node dist/main.cjs preview ./meu-template ./preview.html
+```
+
+`init` exige uma pasta que ainda não exista. A pasta pai precisa existir. O projeto contém `ceupay-template.json` com nome, versão, schema e valores; o código fica em `pages/`, `layouts/`, `components/`, `styles/` e `scripts/`. Edite os arquivos com seu editor habitual. A prévia usa catálogo fictício, sem autenticação ou pagamento.
+
+Abra o HTML gerado no seu navegador. A CLI não inicia servidor nem abre portas. A prévia usa os sanitizadores existentes e bloqueia scripts por CSP; os arquivos JavaScript do projeto ficam preservados para exportação, mas não são executados nessa prévia. Imagens HTTPS externas podem ser carregadas pelo navegador.
+
+Arquivos opcionais `pages/catalog.liquid`, `pages/product.liquid` e `pages/post.liquid` podem ser visualizados com `--page catalog`, `--page product` ou `--page post`. A prévia usa dados fictícios e preserva os arquivos na importação/exportação. Na loja, a apresentação dessas páginas depende de um piloto separado, inicialmente desligado. Variantes, campos obrigatórios, carrinho, autenticação e pagamento continuam controlados pela plataforma.
+
+## Importar e exportar o formato existente
+
+```sh
+node dist/main.cjs import ./ceupay-template-exportado.json ./projeto-importado
+node dist/main.cjs export ./projeto-importado ./ceupay-template-editado.json
+```
+
+O JSON exportado mantém o contrato do painel. Os comandos locais não publicam na loja.
+
+Código, exportações e arquivos de operação existentes não são sobrescritos. Validação recusa links simbólicos, caminhos fora do formato permitido, arquivos grandes, Liquid inválido e dados que seriam silenciosamente truncados pelos validadores. Erros não imprimem o conteúdo do template. Não apague seus arquivos para contornar uma falha; corrija o conteúdo ou escolha outro destino.
+
+## Baixar da loja
+
+Configure `CEUPAY_API_KEY` no ambiente protegido. A CLI não aceita a chave como argumento, não grava credenciais e não desativa a verificação TLS. O proprietário deve delegar `templates:read` e, para publicar/restaurar, `templates:write` em uma chave `cc_prod_`. Chaves de teste só consultam.
+
+```sh
+node dist/main.cjs pull ./template-da-loja
+node dist/main.cjs history --limit 20
+node dist/main.cjs history --before 5 --limit 20
+```
+
+Uma loja sem template customizado exige escolha de modelo: `pull ./novo-template --base horizonte`. `--revision 3` baixa uma versão anterior para inspeção. A CLI salva origem, loja, revisão e checksum em `.ceupay-remote.json`, sem a chave. Para outro servidor, configure `--api-origin https://sua-api.example` ou `CEUPAY_API_ORIGIN`; um arquivo local nunca escolhe sozinho o destino que receberá a credencial. `--store UUID` confere explicitamente a loja associada à chave.
+
+## Preparar e publicar
+
+```sh
+node dist/main.cjs validate ./template-da-loja
+node dist/main.cjs preview ./template-da-loja ./preview.html
+node dist/main.cjs prepare-publish ./template-da-loja ./publicacao.json
+# Revise publicacao.json: loja, origem, revisão e conteúdo.
+node dist/main.cjs publish ./template-da-loja ./publicacao.json --yes
+```
+
+Preparar salva uma operação nova antes de qualquer escrita remota. Publicar exige `--yes`, confere o conteúdo preparado e usa o SDK público. Em um projeto criado por `init` ou `import`, a primeira preparação também exige `--store UUID`. Publicação confirmada atualiza somente o vínculo remoto; seus arquivos de código permanecem editáveis. A versão interna do template é atribuída pelo servidor, e a revisão/checksum remotos controlam concorrência.
+
+Se a loja mudou desde o download, a preparação é recusada. Baixe a revisão atual em outra pasta e revise suas alterações. Uma mudança após a preparação retorna `409 template/revision_conflict`. A CLI não avança silenciosamente a base para sobrescrever outra edição.
+
+Após resposta perdida, preserve o arquivo e use a mesma operação:
+
+```sh
+node dist/main.cjs publish ./template-da-loja ./publicacao.json --yes
+# Se o projeto mudou ou ficou bloqueado após uma interrupção:
+node dist/main.cjs replay ./publicacao.json --yes
+```
+
+Não prepare outro UUID para compensar uma resposta incerta. `replay` reenvia a operação original: recupera a confirmação se ela já foi aplicada, ou permite sua primeira execução autorizada se não foi. Informa `replayed`, `revision` e `currentRevision`, sem alterar a pasta local. Se o vínculo não pôde ser atualizado, baixe o tema em nova pasta e revise os arquivos. Perder o recurso templates preserva consultas e recibos existentes, mas bloqueia novas instalações/restaurações. A operação recusada fica no disco para revisão ou retomada após upgrade. Perder o acesso à API, a chave ser revogada ou o piloto ficar indisponível continua bloqueando as chamadas; use o painel autenticado para consultar/remover quando a API não estiver disponível.
+
+## Restaurar uma versão
+
+```sh
+node dist/main.cjs prepare-restore 3 ./restauracao.json --store UUID-DA-LOJA
+# Revise restauracao.json antes de confirmar.
+node dist/main.cjs restore ./restauracao.json --yes
+```
+
+A restauração preserva o histórico e usa revisão/checksum atuais, UUID persistente e snapshot histórico conferido. Depois, baixe o tema atual em nova pasta antes de continuar a edição. Saídas de confirmação mostram metadados, sem despejar o código do template.
+
+## Verificação
+
+Testes usam processos CLI reais, incluindo HTTPS com certificado isolado, confirmação explícita, resposta perdida, vínculo/loja/origem, revisão desatualizada e arquivos preservados. O teste do pacote instala o arquivo em consumidor separado; `SHA256SUMS` acompanha a alpha local. O CI também executa o pacote instalado em Node compatível contra Nest/PostgreSQL reais, junto das verificações de comércio. A publicação da alpha e a liberação do piloto continuam pendentes.