Metadata-Version: 2.4
Name: shakk-code
Version: 0.6.1
Summary: Cliente oficial de terminal do Shakk Code, por Fluqxo
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests<3,>=2.31
Requires-Dist: rich<15,>=13.7
Requires-Dist: textual<9,>=8.2
Requires-Dist: mcp<3,>=2
Requires-Dist: jsonschema<5,>=4.22

# Shakk Code

O Shakk no terminal, conectado à arquitetura atual do produto Shakk (por
Fluqxo). Não usa Ollama nem qualquer modelo legado como alternativa — fala
sempre com o backend oficial do Shakk.

## Instalação simples

```bash
./install.sh
shakk configurar
```

Também é possível instalar com `pipx install .` ou `python3 -m pip install .`.

## Uso

```bash
shakk                          # aplicativo de terminal em tela única
shakk chat "resuma este texto"
shakk configurar               # assistente de configuração
shakk diagnostico              # testa o ambiente e o serviço
shakk atualizar                # verifica e instala atualização com checksum
shakk --version                # mostra a versão instalada
shakk status                   # mostra as escolhas atuais
```

O aplicativo mantém cabeçalho, conversa, configurações e campo de mensagem na
mesma tela, sem empilhar a saída de cada comando. Use `Ctrl+,` para abrir as
configurações, `Ctrl+L` para começar uma nova conversa, `Shift+Tab` para alternar
o modo de trabalho e `F1` para a ajuda (os comandos de configuração permanecem
como fallback em terminais que não enviam Shift+Tab).
Na conversa interativa, `/ajuda` apresenta os comandos em linguagem simples.
As conversas ficam em `~/.local/state/shakk-code/conversas` e a configuração
em `~/.config/shakk-code`, sempre com permissões privadas.

## Conectar ao site

No site Shakk, abra **Agente → Parear CLI**, gere o código e execute:

```bash
shakk parear 123456
shakk
```

O primeiro comando cria a conexão segura. Ao abrir `shakk`, você conversa no
terminal e o computador também fica disponível para solicitações enviadas pelo
site. Para deixar somente o atendimento remoto aberto, sem a interface, use
`shakk agente`.

O modo (Rápido, Autônomo ou Profundo) escolhido no site acompanha cada
pedido. O modo de trabalho também acompanha o pedido e pode ser alterado no
site ou com `/trabalho` dentro do CLI:

- **Manual:** confirma edições e comandos.
- **Aceitar edições:** edita arquivos automaticamente e confirma comandos.
- **Planejar:** oferece somente leitura e planejamento, sem alterações.
- **Automático:** executa autonomamente as ações normais necessárias ao objetivo,
  inclusive shell completo. Um Risk Interceptor determinístico separa os poucos
  efeitos excepcionalmente perigosos ou fora do escopo.

Respostas já concluídas possuem identificação idempotente e não são processadas
novamente quando o CLI é reiniciado.

## Comandos demorados e autenticação local

Comandos não herdam a entrada de texto nem o terminal interativo do CLI. Quando
o prazo termina, o executor solicita o encerramento do grupo local de processos,
preserva a saída parcial filtrada e informa o timeout sem declarar sucesso.
Isso não desfaz alterações parciais nem garante encerrar processos remotos ou
que escaparam do grupo. Se a limpeza falhar, a tarefa pausa para verificação.

Quando `sudo` informa que precisa de senha/terminal, a tarefa pede autenticação
local e pausa, sem repetir chamadas ao modelo. Nunca envie a senha pelo chat.
Para trabalho longo, use `process_start` e acompanhe por `process_id` em vez de
aguardar um comando que já atingiu o tempo limite.

## Ferramentas e segurança

O Runtime expõe 25 ferramentas para filesystem, patch, processos, Git, LSP com
fallback, pesquisa web, Skills, plano e interação estruturada com o usuário.
No modo manual, mutações relevantes pedem autorização. Em aceitar edições,
mudanças de arquivo são automáticas. Em automático, shell funcional (pipes,
redirecionamentos, encadeamentos e subprocessos) é permitido dentro do objetivo;
o Risk Interceptor bloqueia ou eleva apenas riscos excepcionais, mantendo trilha
de auditoria e grants persistentes por tarefa.

Arquivos de credenciais usam uma inspeção protegida separada. Cada acesso pede
confirmação local, inclusive no modo automático, e informa somente formato,
permissões, nomes de campos configurados e fingerprint pública quando aplicável.
Valores secretos não são enviados ao modelo. A leitura comum também bloqueia
arquivos e conteúdos sensíveis, e toda saída de ferramenta passa por uma última
camada de ocultação antes de chegar ao modelo.

Quando a tarefa precisa usar a credencial, o Shakk executa um processo local com
o arquivo ou campo escolhido e devolve somente a saída já protegida. Também pode
criar arquivos `.env`/JSON, alterar ou remover campos e corrigir permissões. O
novo valor é digitado numa entrada local mascarada, fora da conversa, e cada
operação exige autorização explícita.


## Tarefas recorrentes (0.6, em preparação)

```bash
shakk agendar "resuma os commits de ontem" --quando "diario 08:00"
shakk agendar "veja se os testes passam" --quando "a cada 2h" --cd ~/projeto
shakk agendamentos                 # lista; também: pausar, retomar, remover, executar, saida <id>
shakk agendador                    # deixa rodando (ou: shakk agendador --uma-vez no cron)
```

Sintaxe: `a cada 30m|2h|1d` (mínimo 5 min), `diario HH:MM`, `semanal seg,qua HH:MM`. Ninguém acompanha uma execução agendada,
então o modo padrão é `planejar` (somente leitura); `edicoes` e `automatico` exigem `--confirmo-efeitos`. Execução perdida
(computador desligado) roda uma vez, não em rajada. Cada execução grava a saída em arquivo privado
(`shakk agendamentos saida <id>`). Só um agendador roda por vez.

## Sessões (0.6, em preparação)

```bash
shakk sessoes                          # lista as conversas salvas (--arquivadas para as guardadas)
shakk sessoes exportar <id> -o conversa.md        # ou --formato json; segredos são ocultados
shakk sessoes importar conversa.json   # só o esquema esperado entra; começa com aviso de "histórico de terceiros"
shakk sessoes bifurcar <id> --ate 6    # nova sessão com as 6 primeiras mensagens; a original não muda
shakk sessoes arquivar <id>            # e desarquivar <id>
```

Importe apenas arquivos em que você confia: o conteúdo vira histórico enviado ao modelo.


## Plugins e marketplace (0.6)

```bash
shakk plugins instalar ./meu-plugin        # pasta ou .zip local
shakk plugins marketplace https://exemplo.com/indice.json   # índice do marketplace (https)
shakk plugins buscar revisao  &&  shakk plugins instalar revisao
shakk plugins                              # lista; também: info <nome>, remover <nome>
```

Um plugin traz **somente comandos de barra** em Markdown (`plugin.json` + `comandos/*.md`) e aparecem como `/<plugin>-<comando>`.
Scripts, hooks e servidores MCP **não são aceitos**: seriam código de terceiros. O pacote do marketplace só instala por https,
com tamanho limitado e SHA-256 do índice conferido; caminhos fora do pacote e links simbólicos são recusados. A instalação mostra
o que entra e pede confirmação (`--sim` para pular, depois de ler). Comandos seus e do projeto têm prioridade sobre os do plugin.
Formato do índice: `{"esquema": "shakk-code-marketplace/1", "plugins": [{"nome", "versao", "descricao", "url", "sha256"}]}`.
Ainda não há um marketplace público oficial.

## Sandbox do sistema operacional (0.6)

No modo **pasta** (acesso não total), comandos e processos rodam dentro do **bubblewrap** (Linux): o sistema fica somente leitura,
só a pasta de trabalho (e caches de pacotes) aceita escrita, `/tmp` fica legível e não gravável (temporários vão para um
`/var/tmp` privado), credenciais (`~/.ssh`, nuvem, tokens do Shakk) ficam ocultas e o processo morre junto com o CLI. É uma segunda
barreira, além do Risk Interceptor, para o que a análise do texto do comando não enxerga.

- `shakk status` e `shakk diagnostico` mostram se está ativo. Sem bubblewrap funcional o comando roda como antes e isso é informado
  (instale com `sudo apt install bubblewrap`).
- `SHAKK_CODE_SANDBOX=estrito` esconde a casa inteira e corta a rede; `desligado` desativa. Acesso **total** nunca usa sandbox.
- Não há sandbox em macOS e Windows nesta versão: lá vale só o Risk Interceptor.

## Variáveis opcionais

- `SHAKK_CODE_URL`: endereço de uma instalação própria do Shakk.
- `SHAKK_CODE_CONFIG_DIR`: pasta alternativa de configuração.
- `SHAKK_CODE_STATE_DIR`: pasta alternativa para o histórico local.
Cada computador mantém uma identidade própria. Você pode parear várias máquinas,
selecionar o destino no Chat Web/PWA e desconectar apenas uma instância.

Requisitos: Python 3.10+, Windows 10/11, macOS 11+ ou Linux com suporte ao Python.
O wheel é `py3-none-any`, sem dependência de AVX/AVX2; x86_64, arm64/aarch64 e
arquiteturas que executem as dependências Python puras seguem pelo mesmo caminho leve.
## MCP

Crie o arquivo com `shakk mcp criar` (grava o exemplo em `~/.config/shakk-code/mcp.json`, sem sobrescrever; `shakk mcp exemplo` só mostra), ajuste e confira com
`shakk mcp testar` (conecta em cada servidor e verifica se as ferramentas permitidas existem; `shakk mcp` lista). Habilite somente
as ferramentas necessárias. O Shakk Code aceita servidores locais `stdio` e
servidores remotos Streamable HTTP. Nesta versão, apenas ferramentas declaradas
simultaneamente em `allow` e `read_only` entram no catálogo do modelo; comandos
`stdio` são iniciados sem shell e segredos podem ser mapeados por `env_from`.
