Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions .claude/skills/term7-contribute/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
name: term7-contribute
description: >
The term7 contribution flow: which branch to start from, how to name branches, Conventional Commit
messages and how they drive semantic-release versions, and how to open the pull request (target dev,
fill the PR template). Use whenever you are about to create a branch, write a commit message, commit,
push, open or describe a PR, or the user asks how to contribute or release — even for a one-line fix.
Gatilhos em português: "cria uma branch", "commita", "mensagem de commit", "abre o PR", "manda o PR",
"como contribuir", "qual branch", "vai gerar release?".
---

# Contribuindo com o term7

Commit e push só quando o usuário pedir. Este guia diz *como*, não autoriza fazer.

## Branch

- Parta sempre da `dev` atualizada: `git fetch origin && git switch -c feat/<assunto> origin/dev`.
- Nomes: `feat/...`, `fix/...` (também `docs/...`, `chore/...`, `refactor/...`), curtos e em português,
como `fix/comentar-trecho-removido`.
- **Nunca commite direto na `dev` nem na `main`**, e nunca apague a `dev` (nem com `--delete-branch`).

## Commits

[Conventional Commits](https://www.conventionalcommits.org/pt-br/): o semantic-release lê as mensagens
da `main` e decide a versão sozinho, então o prefixo errado gera a versão errada (ou nenhuma).

| Prefixo | Efeito na versão |
|---------------------------------------------------|-------------------|
| `fix:` | patch (1.0.**1**) |
| `feat:` | minor (1.**1**.0) |
| `feat!:` ou rodapé `BREAKING CHANGE:` | major (**2**.0.0) |
| `docs:`, `chore:`, `refactor:`, `style:`, `test:`, `ci:` | sem release |

- Descrição em português, no imperativo, minúscula: `feat: abrir arquivo do diff no visualizador`.
- Escopo opcional entre parênteses: `fix(revisão): comentar trecho removido no modo alterações`.
- Use `fix:`/`feat:` só pro que o usuário do app percebe; ajuste interno é `refactor:`/`chore:`.

## Pull request

1. Antes de abrir, valide como descrito na skill `term7-dev` (`npm run build`, testes, `cargo check`
sem warnings, teste no app instalado quando houver mudança de interface).
2. Abra o PR **para a `dev`**: `gh pr create --base dev`.
3. Preencha o template de PR de `.github/` (leia o arquivo e siga as seções dele; não substitua por um
texto livre). Diga o que mudou e como testar; prints ou GIFs em mudança visual.
4. No PR o CI só compila o `.deb`, como check. Nada é publicado.

## Releases

- A `main` só recebe o PR `dev → main`. Cada merge nela gera release: o CI calcula a versão, compila
o `.deb`, anexa na release e apaga as releases além das 3 mais recentes.
- Merge na `dev` não gera release; tudo acumula até o próximo `dev → main`.
66 changes: 66 additions & 0 deletions .claude/skills/term7-dev/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
name: term7-dev
description: >
How to build, test and validate a change in term7 (Tauri 2 + Vue 3/TypeScript + xterm.js), plus the code
conventions to follow when editing src/ or src-tauri/. Use whenever you change code in this repo, need to
compile, run tests, type-check, run cargo check/test/clippy, build the .deb, install it locally or try the
app — even if the user only says "fix this" or "add X". Gatilhos em português: "compila", "roda os testes",
"valida a mudança", "gera o .deb", "instala pra testar", "cargo check", "testar no app", "mexer no Rust/Vue".
---

# Desenvolvendo no term7

## Validar uma mudança

Rode tudo isto antes de dar a mudança por pronta. O CI compila o `.deb` no PR, mas warnings e testes são
responsabilidade de quem muda.

```sh
npm run build # vue-tsc --noEmit + vite build; obrigatório depois de mexer em src/
npm test # testes do frontend (vitest)

# Rust: sempre pelo container (o ambiente de referência não tem Rust instalado)
docker compose run --rm --no-deps dev bash -c "cd src-tauri && cargo check"
docker compose run --rm --no-deps dev bash -c "cd src-tauri && cargo test"
# clippy: o rustup do container é o perfil minimal, sem o clippy
docker compose run --rm --no-deps dev bash -c "cd src-tauri && rustup component add clippy && cargo clippy"
```

- `cargo check` precisa passar **sem warnings**, não só sem erros.
- Os testes Rust ficam no próprio arquivo, em `#[cfg(test)] mod tests`, com nomes em português
(ex.: `fn pasta_do_projeto()`). Siga o mesmo padrão.
- Se `npm test` ainda não existir no `package.json`, avise em vez de inventar outro comando.

## Testar o app de verdade

Interação (digitar, clicar, desempenho) se testa no app instalado, não no Docker:

```sh
docker compose run --rm build # gera o .deb em dist-deb/ (mesmo Ubuntu 24.04 do CI)
scripts/install-local.sh # instala em ~/.local, sem sudo (--remove desinstala)
~/.local/bin/term7
```

`docker compose run --rm dev` abre a interface, mas o container não tem GPU: tudo fica lento e o
xterm.js com WebGL não se comporta como no app real. Use o Docker só pra compilar.
Quem tem Rust e as libs do Tauri na máquina pode usar `npm run tauri dev` (hot reload).

## Convenções que importam ao editar

- **Comandos Tauri que fazem I/O ou chamam processos** (git, gh, arquivos, `/proc`) são `async` e usam
`spawn_blocking`: comando síncrono roda na thread da janela e trava a interface.
- **Comando Tauri novo:** registre em `src-tauri/src/lib.rs`; permissões de janela em
`src-tauri/capabilities/default.json`.
- **Saída do PTY** vai como bytes brutos (`InvokeResponseBody::Raw`), nunca JSON.
- **`gh`** precisa funcionar com a versão 2.4 (Ubuntu 22.04): sem `run list --branch` nem `workflowName`.
Consultas ao GitHub são espaçadas (60 s; 15 s com action rodando).
- **Git em polling** usa `GIT_OPTIONAL_LOCKS=0`, pra não disputar o `index.lock` com o usuário.
- **Botões que não devem roubar o foco do terminal** usam `@mousedown.prevent`.
- **TypeScript fica em `~5.9`**: o `vue-tsc` não suporta o 7. Não suba essa dependência.
- O `identifier` (`br.tec.code7.term7`) e o `StartupWMClass` de `src-tauri/term7.desktop` precisam
continuar iguais (é por ele que o Wayland identifica a janela).
- **Idioma:** comentários, textos da interface e docs em português do Brasil, com acentuação;
identificadores em inglês. Comentários curtos que explicam o *porquê*, nunca repetem o código.

A estrutura de pastas e o papel de cada arquivo estão no `CLAUDE.md` da raiz. Se a mudança mexe com
GitHub ou Claude Code, veja também a skill `term7-integrations`.
73 changes: 73 additions & 0 deletions .claude/skills/term7-integrations/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
name: term7-integrations
description: >
Orientation for changing term7's GitHub (gh CLI: PR, checks, action runs) and Claude Code integrations
(hooks/TERM7_PANE tab state, suggested commands, subagents menu, MCP list, usage limits via statusLine
and headless get_usage, CLAUDE_CONFIG_DIR). These are the core of the product and must not regress. Use
whenever you touch gh.rs, claude.rs, suggest.rs, agents.rs, usage.rs, github.ts or useGithub.ts, parse
anything from ~/.claude (sessions, projects/*.jsonl transcripts, subagents, settings.json), or change
polling — even for a small parser tweak. Gatilhos em português: "integração com o GitHub/Claude",
"status do PR", "checks/actions", "hooks do Claude", "agentes", "comandos sugeridos", "uso do Claude",
"MCP", "parser do jsonl".
---

# Integrações com o GitHub e o Claude Code

Estas integrações são o coração do term7 e hoje funcionam bem pra quem mantém o projeto. O objetivo de
qualquer mudança aqui é **não quebrar o que já funciona**: leia o arquivo inteiro antes de mexer, mude o
mínimo e prove com teste.

## Mapa

| Arquivo | O que faz |
|---|---|
| `src-tauri/src/gh.rs` | `gh_pr`, `gh_runs`, `open_url`. Roda o `gh` na pasta da aba; devolve o JSON cru (`GhResult`: `missing`, `unauthenticated`, `none`, `ok`, `error`) e quem interpreta é o frontend. |
| `src/lib/github.ts` | Tipos e interpretação do JSON do `gh` (PR, checks, runs). |
| `src/lib/useGithub.ts` | Polling: `IDLE_MS = 60_000`, `PENDING_MS = 15_000` (com check/action pendente). |
| `src-tauri/src/claude.rs` | Hooks do Claude (estado da aba), leitura/gravação do `settings.json` do Claude, `claude_proc` (binário, cwd e ambiente via `/proc`) e a lista de MCPs. |
| `src-tauri/src/suggest.rs` | Comandos sugeridos: acha a sessão do processo e extrai comandos das últimas respostas. |
| `src-tauri/src/agents.rs` | Subagentes da sessão e a linha do tempo de cada um. |
| `src-tauri/src/usage.rs` | Uso da assinatura (limites de 5 h, 7 dias e por modelo) e contexto da sessão. |

## Fontes de dados

**GitHub.** Só pelo binário `gh`, que cuida do login e de achar o repositório pelos remotes.
- Compatível com o **gh 2.4** (Ubuntu 22.04): use só os campos de `PR_FIELDS`/`RUN_FIELDS` de `gh.rs`;
sem `run list --branch` nem `workflowName`. Campo novo = confirme que existe no 2.4.
- Não encurte os intervalos de 60 s / 15 s: são pra não gastar o limite da API do usuário.

**Claude Code.** Tudo é lido do processo `claude` em primeiro plano na aba e dos arquivos dele.
- **Pasta de configuração:** `CLAUDE_CONFIG_DIR` lido do **ambiente do processo** (`/proc/<pid>/environ`),
não do app: a variável pode estar só no `~/.zshrc`, que o app aberto pelo menu não vê. Sem ela,
`~/.claude`. Nunca assuma `~/.claude` fixo.
- **Estado da aba (hooks):** o term7 exporta `TERM7_PANE` no shell de cada aba; os hooks que ele instala
no `settings.json` do Claude gravam o estado em `$XDG_RUNTIME_DIR/term7/claude-<pane>`. Fora do term7
a variável não existe e o hook não faz nada. A instalação só mexe nas entradas marcadas com
`TERM7_PANE`, preserva o resto do arquivo, faz cópia do original na primeira vez e troca atômica.
- **Sessão e histórico:** `<config>/sessions/<pid>.json` dá o id da sessão e o `cwd`;
`<config>/projects/<slug>/<id>.jsonl` é o histórico (slug: `/home/x/a.b` → `-home-x-a-b`). Como o `cwd`
acompanha o `cd` dentro do Claude, há fallback procurando o `<id>.jsonl` em todas as pastas de
`projects/`. Só o fim do arquivo é lido (ele cresce a sessão toda) e há cache por arquivo.
- **Subagentes:** `projects/<slug>/<sessão>/subagents/agent-<id>.meta.json` (tipo, descrição, modelo, se
terminou) e `agent-<id>.jsonl` (mensagens e uso de tokens).
- **MCPs:** nomes do `.mcp.json` e do escopo local no `.claude.json` (da pasta até antes da home), ou os
globais a pedido; o status vem de `claude mcp get <nome>` com o binário e o ambiente da aba. Só Status,
URL e Command são lidos, e o endereço é limpo de credenciais: headers e env (onde ficam tokens) nunca.
- **Uso:** os `rate_limits` só chegam ao comando do `statusLine`. O term7 põe um wrapper (marcado com
`TERM7_USAGE=1`) na frente do comando do usuário, guarda o JSON em
`$XDG_RUNTIME_DIR/term7/usage-<pasta>.json` e repassa ao original, que desenha a linha igual; o original
fica em `<config>/term7-statusline.json`, pra desfazer. Os limites por modelo vêm de um Claude headless
igual ao da aba com o control request `get_usage`, a cada 5 min, sem hooks e sem mensagem (não gasta uso).

## Regras ao mudar

- **Parser mudou, teste junto.** Toda mudança em leitura de `.jsonl`, `meta.json`, `settings.json`,
saída do `gh` ou do `claude mcp get` vem com teste unitário no `#[cfg(test)] mod tests` do arquivo,
usando fixture com o **formato real** (copie uma linha de verdade e anonimize), não um JSON inventado
mínimo. Mantenha os testes existentes passando; se um precisa mudar, explique por quê no PR.
- Formato desconhecido ou campo ausente degrada em silêncio (lista vazia, `None`), nunca derruba a aba.
- Não altere nada do usuário que não seja do term7 no `settings.json` do Claude, e mantenha o desfazer.
- Nunca leia nem mande pro frontend tokens, headers ou variáveis de ambiente com credenciais.
- I/O e processos (`gh`, `claude`, `/proc`, arquivos) em comando `async` + `spawn_blocking`.
- Valide como na skill `term7-dev` (inclui `cargo test` no Docker) e teste no app instalado, com um
Claude rodando numa aba e um repositório com PR, antes de abrir o PR.
68 changes: 68 additions & 0 deletions .github/ISSUE_TEMPLATE/01_bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
name: 🐞 Bug report / Relatar bug
description: Something doesn't work as expected. / Algo não funciona como deveria.
labels: ["bug", "triage"]
body:
- type: markdown
attributes:
value: |
Thanks for reporting! Please [search existing issues](https://github.com/code7tecbr/term7/issues?q=is%3Aissue) first. English or Portuguese are both fine.
Valeu por relatar! [Procure nas issues](https://github.com/code7tecbr/term7/issues?q=is%3Aissue) antes. Pode escrever em português ou inglês.

**Security issues / Falhas de segurança:** don't open an issue, see [SECURITY.md](https://github.com/code7tecbr/term7/blob/dev/SECURITY.md).
- type: dropdown
id: area
attributes:
label: Area / Área
options:
- Terminal (output, input, links, paths)
- Tabs, groups, session / Abas, grupos, sessão
- GitHub (PR, checks, actions, branches)
- Claude Code (status, agents, MCP, usage, suggestions, review)
- Files and explorer / Arquivos e explorador
- Voice dictation / Ditado por voz
- Update and install / Atualização e instalação
- Other / Outra
validations:
required: true
- type: textarea
id: what
attributes:
label: What happened? / O que aconteceu?
description: And what did you expect instead? / E o que você esperava?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce / Como reproduzir
placeholder: |
1.
2.
3.
validations:
required: true
- type: input
id: version
attributes:
label: term7 version / Versão do term7
description: Right corner of the status bar. / Canto direito da barra de status.
placeholder: v1.17.3
validations:
required: true
- type: input
id: os
attributes:
label: Distro and desktop / Distro e desktop
placeholder: Ubuntu 24.04, GNOME (Wayland)
validations:
required: true
- type: input
id: tools
attributes:
label: gh and claude versions (for integration bugs) / Versões do gh e do claude (bugs de integração)
description: "`gh --version` and `claude --version`"
- type: textarea
id: extra
attributes:
label: Screenshots, GIFs or logs / Prints, GIFs ou logs
description: Run `term7` from another terminal to see its logs. Hide anything private (anonymous mode helps). / Rode o `term7` de outro terminal pra ver os logs. Esconda o que for privado (o modo anônimo ajuda).
34 changes: 34 additions & 0 deletions .github/ISSUE_TEMPLATE/02_feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: 💡 Idea / Ideia
description: Suggest a feature or an improvement. / Sugira uma funcionalidade ou melhoria.
labels: ["enhancement", "triage"]
body:
- type: markdown
attributes:
value: |
Check the [open issues](https://github.com/code7tecbr/term7/issues) first: the roadmap lives there. English or Portuguese are both fine.
Confira as [issues abertas](https://github.com/code7tecbr/term7/issues) antes: o roadmap fica lá. Pode escrever em português ou inglês.
- type: textarea
id: problem
attributes:
label: What problem does it solve? / Que problema resolve?
description: Describe the situation in your workflow. / Descreva a situação no seu dia a dia.
validations:
required: true
- type: textarea
id: proposal
attributes:
label: How would it work? / Como funcionaria?
description: What you would see and do in term7. Mockups welcome. / O que você veria e faria no term7. Rascunhos são bem-vindos.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives / Alternativas
description: Other ways you considered, or how other tools do it. / Outros jeitos que você pensou, ou como outras ferramentas fazem.
- type: checkboxes
id: contribute
attributes:
label: Contribution / Contribuição
options:
- label: I'd like to implement this. / Quero implementar isso.
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: 🔒 Security issue / Falha de segurança
url: https://github.com/code7tecbr/term7/security/advisories/new
about: Report privately, not in a public issue. / Relate em particular, não numa issue pública.
18 changes: 18 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<!-- PRs go to `dev`. / PRs vão pra `dev`. Title in Conventional Commits: `feat: ...`, `fix: ...` -->

## What / O que muda

<!-- Closes #123 -->

## How to test / Como testar

<!-- Steps in the installed app. / Passos no app instalado. -->

## Checklist

- [ ] Branch from `dev`, PR to `dev` / Branch a partir da `dev`, PR pra `dev`
- [ ] `npm test` and `npm run build` pass / passam
- [ ] `cargo check` and `cargo test` pass with no warnings / passam sem warnings
- [ ] Tested in the installed app (`scripts/install-local.sh`) / Testado no app instalado
- [ ] New logic has tests / Lógica nova tem teste
- [ ] Screenshots or GIF for visual changes / Prints ou GIF em mudança visual
7 changes: 6 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# 2. Compila o .deb e anexa direto na release (sem upload de artifact do Actions).
# 2. Roda os testes, compila o .deb e anexa direto na release (sem upload de artifact do Actions).
build-deb:
needs: version
# Fora da main o job version é pulado; !cancelled() deixa este rodar mesmo assim.
Expand Down Expand Up @@ -95,6 +95,11 @@ jobs:
node-version: 24
cache: npm
- run: npm ci
# Testes antes do bundle: o cargo test precisa do dist/ (o Tauri embute o frontend).
- run: npm test
- run: npm run build
- run: cargo test --locked
working-directory: src-tauri
- name: Aplica a versão da release
if: env.VERSION != ''
run: npm version "$VERSION" --no-git-tag-version --allow-same-version
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ src-tauri/target
src-tauri/gen/schemas
*.log
dist-deb
src-tauri/THIRD_PARTY_LICENSES.md
Loading