clawfast 1.0.0

package/README.md

@@ -0,0 +1,227 @@
+# HackerAI - CLI local
+
+Versao de terminal do HackerAI. Ela reaproveita o prompt e as ferramentas do
+projeto, roda na sua maquina, sem login e sem limites de uso do app web, usando
+suas proprias chaves de modelo.
+
+## Como rodar
+
+Na raiz do projeto:
+
+```bash
+corepack pnpm@10.33.2 cli
+# ou, se o pnpm ja estiver no PATH:
+pnpm cli
+```
+
+No Windows tambem da para usar o atalho:
+
+```bat
+cli\hackerai.bat
+```
+
+Esse atalho inicia em modo local aberto: ele define `CLI_SHELL=cmd.exe`,
+`CLI_SHELL_FLAG=/C` e `HACKERAI_CLI_GUARDRAILS=off` apenas para essa sessao.
+
+Digite seu pedido e o agente executa comandos no host local. Saia com `/exit`.
+
+## Shell no Windows
+
+O CLI escolhe o shell automaticamente:
+
+- Windows com Git Bash instalado: usa `bash.exe -c`.
+- Windows sem Git Bash: usa `cmd.exe /C`.
+- Linux/macOS: usa `/bin/bash -c`.
+
+Voce pode sobrescrever:
+
+```powershell
+$env:CLI_SHELL="cmd.exe"
+$env:CLI_SHELL_FLAG="/C"
+pnpm cli
+```
+
+Ou apontar para Git Bash:
+
+```powershell
+$env:HACKERAI_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
+pnpm cli
+```
+
+## Modo local aberto
+
+Por padrao, o CLI ainda respeita os guardrails de comandos perigosos. Para uma
+sessao local explicitamente aberta via PowerShell:
+
+```powershell
+$env:CLI_SHELL="cmd.exe"
+$env:CLI_SHELL_FLAG="/C"
+$env:HACKERAI_CLI_GUARDRAILS="off"
+pnpm cli
+```
+
+Isso desliga os guardrails apenas no CLI local. A aplicacao web continua usando
+as configuracoes normais de seguranca.
+
+## Kali, ZAP, Nikto e Nuclei
+
+No Windows, o caminho recomendado para ferramentas Kali e usar WSL/Kali. Primeiro
+verifique se a distro existe:
+
+```bat
+wsl -l -v
+```
+
+Se precisar instalar a distro:
+
+```bat
+wsl --install -d kali-linux
+```
+
+Dentro do Kali/WSL, instale os scanners:
+
+```bat
+wsl -d kali-linux -- bash -lc "sudo apt update && sudo apt install -y zaproxy nikto nuclei"
+```
+
+Verifique as ferramentas:
+
+```bat
+wsl -d kali-linux -- bash -lc "zaproxy -h >/dev/null || owasp-zap -h >/dev/null; nikto -Version; nuclei -version"
+```
+
+Exemplos de execucao a partir do Windows `cmd.exe`:
+
+```bat
+wsl -d kali-linux -- bash -lc "cd /mnt/c/Users/Usuario/OneDrive/Documentos/Corel/hackerai/SPRIT && nikto -host https://example.com -nointeractive -maxtime 10m -Format htm -output nikto.html"
+wsl -d kali-linux -- bash -lc "cd /mnt/c/Users/Usuario/OneDrive/Documentos/Corel/hackerai/SPRIT && nuclei -u https://example.com -s low,medium,high,critical -jle nuclei.jsonl -me nuclei_markdown -timeout 10 -retries 1"
+```
+
+Para OWASP ZAP via Docker no Windows `cmd.exe`:
+
+```bat
+docker pull ghcr.io/zaproxy/zaproxy:stable
+docker run --rm -v "%cd%:/zap/wrk/:rw" -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py -t https://example.com -r zap_baseline.html -J zap_baseline.json -I
+docker run --rm -v "%cd%:/zap/wrk/:rw" -t ghcr.io/zaproxy/zaproxy:stable zap-full-scan.py -t https://example.com -m 5 -r zap_full.html -J zap_full.json -I
+```
+
+## Scripts e arquivos
+
+Scripts e codigo-fonte devem ser criados pela ferramenta de arquivo dentro do
+workspace do agente, normalmente `./SPRIT`. O terminal fica para executar,
+testar, compilar, instalar dependencias e salvar relatorios/logs.
+
+O CLI bloqueia criacao de codigo-fonte por comandos como `echo > file.py`,
+`cat <<EOF > file.py`, `tee file.py`, `Set-Content file.py`, `Out-File file.py`
+e `curl -o file.py`. Redirecionamento continua liberado para relatorios como
+`.txt`, `.json`, `.csv`, `.md`, `.html` e `.log`.
+
+## OpenAI e ChatGPT
+
+O CLI pode usar a OpenAI oficial por `OPENAI_API_KEY`. Isso nao e login do
+ChatGPT: a API da OpenAI autentica chamadas com credenciais de API no servidor.
+O modelo `chat-latest` foi adicionado como opcao por ser o caminho de API mais
+proximo da experiencia ChatGPT Instant.
+
+## Hugging Face
+
+O CLI tambem pode usar o Hugging Face Inference Providers Router por
+`HUGGINGFACE_API_KEY` ou `HF_TOKEN`. Ele usa o endpoint OpenAI-compatible de chat
+completion:
+
+```env
+HUGGINGFACE_API_KEY=...
+HUGGINGFACE_BASE_URL=https://router.huggingface.co/v1
+```
+
+Modelos adicionados:
+
+- `Qwen/Qwen3.6-35B-A3B`
+- `zai-org/GLM-5.1-FP8`
+- `deepseek-ai/DeepSeek-V4-Flash`
+
+Modelos pedidos mas nao selecionaveis no chat router:
+
+- `XiaomiMiMo/MiMo-V2.5-Pro-FP4-DFlash`: substituido por
+  `zai-org/GLM-5.1-FP8`, que responde no chat router.
+- `nvidia/DeepSeek-V4-Flash-NVFP4`: o router retorna que nao e um modelo de
+  chat. O CLI usa `deepseek-ai/DeepSeek-V4-Flash` como alternativa roteavel.
+
+A disponibilidade e o suporte a tool-calling podem variar por modelo/provedor
+no router. Se um modelo da Hugging Face falhar durante uso de ferramentas, use
+`/model auto` ou escolha um modelo OpenRouter/OpenAI no seletor.
+
+## Configuracao
+
+As chaves ficam em `../.env.local`, que nao deve ser versionado:
+
+```env
+OPENROUTER_API_KEY=...
+HUGGINGFACE_API_KEY=...
+HUGGINGFACE_BASE_URL=https://router.huggingface.co/v1
+OPENAI_API_KEY=...
+NVIDIA_API_KEY=...
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+```
+
+Variaveis opcionais:
+
+- `CLI_SHELL`: shell usado para executar comandos.
+- `CLI_SHELL_FLAG`: flag de execucao do shell (`-c`, `/C`, `-Command`).
+- `CLI_WORKDIR`: diretorio de trabalho do agente. Padrao: `./SPRIT`.
+- `HACKERAI_BASH_PATH`: caminho para `bash.exe` no Windows.
+- `HACKERAI_CLI_GUARDRAILS`: use `off` para desligar guardrails no CLI.
+- `HACKERAI_CLI_GUARDRAILS_CONFIG`: configuracao manual no formato `id:true`.
+- `HACKERAI_CLI_DUMP_SYSTEM_PROMPT`: use `1` para salvar o prompt completo em
+  `SPRIT/system-prompt.txt` ao iniciar o CLI.
+
+O CLI carrega o prompt por `import { systemPrompt } from "@/lib/system-prompt"`
+e valida marcadores obrigatorios antes de chamar qualquer modelo. Se o prompt
+vier incompleto, a sessao falha em vez de usar uma versao reduzida. Use
+`/system` para ver o prompt ativo, a fonte e a checagem.
+
+## Modelos
+
+A ordem de fallback do CLI e `CLI_MODEL_CHAIN` em
+[`../lib/ai/providers.ts`](../lib/ai/providers.ts):
+
+1. OpenRouter `z-ai/glm-4.5-air:free`
+2. OpenRouter `qwen/qwen3-coder:free`
+3. Hugging Face `Qwen/Qwen3.6-35B-A3B`, se `HUGGINGFACE_API_KEY`/`HF_TOKEN`
+   estiver configurada
+4. Hugging Face `zai-org/GLM-5.1-FP8`, se Hugging Face estiver configurada
+5. Hugging Face `deepseek-ai/DeepSeek-V4-Flash`, se Hugging Face estiver
+   configurada
+6. OpenAI `chat-latest`, se `OPENAI_API_KEY` estiver configurada
+
+Somente provedores com chave configurada entram na cadeia. Se um modelo falhar,
+o CLI tenta o proximo automaticamente.
+
+`NVIDIA_API_KEY` continua aceito para testes/diagnostico, mas NVIDIA fica fora
+do fallback do agente porque o endpoint atual retorna `500 "'role'"` depois de
+resultados de ferramenta. Para agente com terminal/arquivos, use OpenRouter ou
+OpenAI.
+
+Dentro do terminal voce pode escolher o modelo da sessao:
+
+```text
+/model       abre o seletor de modelos
+2            fixa o segundo modelo da lista no seletor
+/model openai
+/model auto  volta para fallback automatico
+```
+
+Quando um modelo fica fixo, o CLI usa so ele nas proximas mensagens. O modo
+`auto` volta a tentar a cadeia de fallback na ordem configurada. Dentro do
+seletor, use `cancelar` para sair sem trocar.
+
+## Arquitetura
+
+- `index.ts`: REPL do terminal.
+- `src/agent.ts`: monta o `ToolContext`, carrega o system prompt e registra as tools.
+- `src/local-sandbox.ts`: executa comandos via `child_process`/`fs` no host.
+- `src/local-sandbox-manager.ts`: manager minimo que entrega o sandbox local.
+- `src/console-writer.ts`: imprime a saida de terminal das tools no stdout.
+
+Convex, WorkOS, Trigger.dev, E2B, Stripe, rate limits e entitlements do app web
+ficam fora do CLI local.