create-gkframe

Instalador CLI do GK Framework. Cria uma cópia fiel e completa da pasta .gkframe/ em qualquer projeto, de forma não-destrutiva.

npx create-gkframe

Este README é do pacote instalador, não do framework. A documentação do framework em si vive dentro de .gkframe/ (após a instalação).

O que ele faz

Ao rodar na raiz de um projeto, o create-gkframe:

1. Verifica se já existe uma pasta .gkframe/ no diretório atual. Se existir, ele para imediatamente e não sobrescreve nada.
2. Pede uma confirmação interativa antes de escrever qualquer arquivo.
3. Copia toda a estrutura do framework (as 14 camadas numeradas, INDEX.md, MANIFEST.md, README.md e a pasta project/) para .gkframe/.
4. Cria ou atualiza um CLAUDE.md na raiz com a instrução para a IA consultar .gkframe/INDEX.md no início de cada tarefa (anexa sem sobrescrever, e só se ainda não estiver presente).
5. (Opt-in) Oferece instalar a integração Claude Code — auditores (gk-security-auditor, gk-deadcode-auditor), o comando /gk-audit (o maestro) e os hooks (on-stop, pre-commit), com wiring não-destrutivo do .claude/settings.json e do .git/hooks/pre-commit.
6. (Opt-in) Oferece instalar a integração Cursor — o comando /gk-audit (autocontido) em .cursor/commands/ e uma rule de bootstrap em .cursor/rules/ (gk-framework.mdc, alwaysApply), auto-descobertos pelo Cursor.
7. Imprime um resumo e o próximo passo sugerido.

Sem dependências externas — Node.js puro. Nada de serviço pago: tudo é local (a IA que executa os auditores é a que você já usa).

Flags

• -y, --yes — pula a confirmação interativa (default: só o núcleo agnóstico).
• --claude — instala também a integração Claude Code (funciona com -y).
• --no-claude — nunca instala a integração Claude Code (só o núcleo agnóstico).
• --cursor — instala também a integração Cursor (/gk-audit + rules em .cursor/).
• --no-cursor — nunca instala a integração Cursor.
• --update — atualiza uma .gkframe/ existente para a versão do pacote, preservando 100% do seu .gkframe/project/ (faz backup em .gkframe.bak-<versão>/ antes).
• --force — permite --update em caso de downgrade ou versão instalada ilegível.
• --ci — instala o workflow de CI (.github/workflows/gk.yml) que roda o gk-verify em todo push/PR.
• --no-ci — nunca instala o CI.

Atualizar (upgrade)

Rode npx create-gkframe@latest numa pasta que já tem .gkframe/: ele detecta a versão instalada e oferece atualizar (ou use --update direto). A atualização:

• substitui os arquivos do framework pela versão nova (as 14 camadas, checks, scripts, maestro, hooks);
• preserva 100% do .gkframe/project/ (seu STATE, decisões, invariants.js, PROFILE.json, memória) — só adiciona scaffold novo que faltava;
• migra as camadas (.claude//.cursor/): atualiza os stubs e reaponta o wiring (settings.json, .git/hooks/pre-commit) para o novo layout, limpando a pasta hooks/ órfã da raiz;
• faz backup do estado anterior em .gkframe.bak-<versão>/.

Customize sempre via .gkframe/project/ — arquivos do framework são substituídos no upgrade. Recomendado: commitar antes de atualizar e revisar o diff depois.

Agnosticidade por design: o default é o núcleo agnóstico (.gkframe/ + gk-verify, Node puro, roda em qualquer agente/CI). A camada Claude Code é opcional e só entra se você pedir — assim o framework não fica acoplado a uma ferramenta.

Estrutura do pacote

create-gkframe/
├── index.js            → o instalador (bin) — é o que roda no `npx`
├── sync-template.js    → ferramenta de dev (NÃO publicada) — sincroniza o template
├── package.json
├── README.md           → este arquivo
└── template/
    └── .gkframe/       → cópia fiel do framework distribuída ao usuário
        └── gitignore   → vira `.gitignore` no destino (ver nota abaixo)

Nota sobre o .gitignore: o npm renomeia/descarta arquivos .gitignore ao publicar. Por isso ele é guardado no template como gitignore (sem ponto) e o instalador o grava como .gitignore no projeto do usuário. O conteúdo é idêntico.

Mantendo o template atualizado (antes de publicar)

O template/.gkframe/ é uma cópia da .gkframe/ canônica da raiz do repositório. Sempre que o framework mudar, ressincronize antes de publicar:

# a partir de packages/create-gkframe/
npm run sync-template
#  ou
node sync-template.js

O script copia a .gkframe/ da raiz do repo para template/, normaliza o .gitignore e compara as contagens de arquivos. Se divergirem, ele aborta e avisa — garantindo que nada fique faltando na distribuição.

Testar localmente ANTES de publicar

Nunca publique sem testar. Duas formas:

Opção A — npm pack (mais próximo do publish real)

# a partir de packages/create-gkframe/
npm pack
#  → gera create-gkframe-0.1.0.tgz com exatamente o que seria publicado

# veja o conteúdo do tarball (deve conter template/.gkframe/ inteiro)
tar -tf create-gkframe-0.1.0.tgz

# instale o tarball num projeto de teste vazio
mkdir /tmp/projeto-teste && cd /tmp/projeto-teste
npm init -y
npx /caminho/para/create-gkframe-0.1.0.tgz

Opção B — npm link

# a partir de packages/create-gkframe/
npm link                 # registra o bin globalmente

mkdir /tmp/projeto-teste && cd /tmp/projeto-teste
create-gkframe           # roda o instalador

# ao terminar os testes:
npm unlink -g create-gkframe

Verificar a não-destrutividade

Rode o instalador duas vezes no mesmo diretório:

create-gkframe           # 1ª vez: instala normalmente
create-gkframe           # 2ª vez: DEVE parar com "já existe uma .gkframe/ aqui"

A segunda execução tem de recusar e não alterar nada.

Publicar no npm (quando você decidir)

# a partir de packages/create-gkframe/
npm run sync-template          # garante o template atualizado
npm pack && tar -tf create-gkframe-0.1.0.tgz   # confira o conteúdo
npm login                      # se ainda não estiver logado
npm publish --access public    # publica a versão atual (0.1.0)

Depois de publicado, qualquer pessoa poderá rodar:

npx create-gkframe

Para novas versões, bump a versão em package.json (ex.: npm version patch), rode npm run sync-template e publique novamente.

Licença

MIT.