17-community-commands.md (7814B)
1 # Comandos comunitários 2 3 [← Índice](README.md) 4 5 ## Visão geral 6 7 Estes comandos dão mais vida pubnix ao servidor runv.club: 8 9 - **perfil local** (`runv-profile`) — ficheiros em `~/.runv/profile.json`, `~/.plan` e `~/.project`; 10 - **finger moderno** (`runv-finger`) — ver o perfil público de outro membro; 11 - **listagem de membros** (`runv-who`) — quem está na comunidade e sinais de actividade; 12 - **mural comunitário** (`runv-bulletin`) — mensagens curtas partilhadas no terminal. 13 14 São instalados por [`tools/tools.py`](../tools/tools.py) em `/usr/local/bin` (junto com `runv-help`, `chat`, etc.). A biblioteca partilhada fica em `/usr/local/share/runv/lib/runv_community.py`. 15 16 No login SSH, o MOTD ([`tools/motd/60-runv`](../tools/motd/60-runv)) e `runv-help` listam estes comandos na secção **Comunidade runv**. Ver também [05-tools-and-system-experience.md](05-tools-and-system-experience.md#motd-e-runv-help). 17 18 Não expõem email, chave pública nem fingerprint de `/var/lib/runv/users.json` (excepto `runv-who`, que usa só a lista de usernames em `users.json` quando legível). 19 20 ## `runv-profile` 21 22 ### O que faz 23 24 Gerencia o perfil local público: 25 26 - `~/.runv/profile.json` 27 - `~/.plan` 28 - `~/.project` 29 30 ### Exemplos 31 32 ```bash 33 runv-profile init 34 runv-profile show 35 runv-profile path 36 ``` 37 38 ### Arquivos criados 39 40 | Caminho | Descrição | 41 |---------|-----------| 42 | `~/.runv/profile.json` | Nome, bio, local, links, interesses | 43 | `~/.plan` | Plano actual (texto livre) | 44 | `~/.project` | Projecto actual (texto livre) | 45 46 ### Permissões esperadas 47 48 | Caminho | Modo | 49 |---------|------| 50 | `~/.runv` | `755` | 51 | `~/.runv/profile.json` | `644` | 52 | `~/.plan` | `644` | 53 | `~/.project` | `644` | 54 55 ### Observações 56 57 - `init` **não sobrescreve** ficheiros existentes. 58 - Não guarde dados sensíveis no perfil (são legíveis por outros membros via `runv-finger`). 59 - Contas antigas sem estes ficheiros podem correr `runv-profile init` uma vez. 60 61 --- 62 63 ## `runv-finger` 64 65 ### O que faz 66 67 Mostra o perfil público de outro membro (estilo `finger`). 68 69 ### Exemplo 70 71 ```bash 72 runv-finger pablo 73 ``` 74 75 ### Dados exibidos 76 77 - `~/.runv/profile.json` (campos públicos) 78 - `~/.plan` 79 - `~/.project` 80 - existência e última actualização de `~/public_html/index.html` (como `Home: /~USER/`) 81 82 ### Segurança 83 84 - Não mostra email. 85 - Não mostra chave pública. 86 - Não mostra fingerprint. 87 - Cada ficheiro é lido com limite de **16 KiB**. 88 89 --- 90 91 ## `runv-who` 92 93 ### O que faz 94 95 Lista membros da runv.club com indícios de actividade (homepage, `.plan`, `.project`). 96 97 ### Exemplos 98 99 ```bash 100 runv-who 101 runv-who --active 102 runv-who --limit 20 103 runv-who --json 104 ``` 105 106 ### Fontes de dados 107 108 **Preferencial:** `/var/lib/runv/users.json` (apenas usernames; formatos suportados: lista de objectos com `username`, objecto com chaves = usernames, ou `{ "users": [ ... ] }`). 109 110 **Fallback:** directórios em `/home/` cujo nome passa na regex de username. 111 112 Se `users.json` existir mas for inválido, aparece um aviso e usa-se `/home`. 113 114 ### Campos exibidos 115 116 | Campo | Significado | 117 |-------|-------------| 118 | `username` | Nome Unix | 119 | `homepage` | Sempre `/~USER/` | 120 | `has_homepage` | Existe `~/public_html/index.html` | 121 | `homepage_mtime` | ISO UTC da última modificação da homepage, ou `null` | 122 | `has_plan` | `.plan` existe e não está vazio | 123 | `has_project` | `.project` existe e não está vazio | 124 125 ### Ordenação 126 127 1. Membros com homepage, por data da homepage (mais recente primeiro). 128 2. Membros sem homepage, por ordem alfabética. 129 130 Com `--active`, só entram quem tem homepage **ou** `.plan` **ou** `.project`. 131 132 ### JSON 133 134 `--json` imprime um array JSON só com os campos acima — útil para integração futura com site, Garden, Gotchi ou outros scripts. 135 136 --- 137 138 ## `runv-bulletin` 139 140 ### O que faz 141 142 Mural comunitário simples em terminal (uma linha JSON por post). 143 144 ### Exemplos 145 146 ```bash 147 runv-bulletin 148 runv-bulletin list 149 runv-bulletin post "Hoje configurei meu gopher" 150 runv-bulletin --limit 10 151 runv-bulletin --json 152 ``` 153 154 Sem subcomando, equivale a `list`. 155 156 ### Arquivos usados 157 158 | Caminho | Função | 159 |---------|--------| 160 | `/var/lib/runv/bulletin/posts.ndjson` | Posts (NDJSON) | 161 | `/var/lib/runv/bulletin/posts.lock` | Lock `flock` em escritas | 162 163 Testes locais: 164 165 ```bash 166 export RUNV_BULLETIN_PATH=/tmp/runv-bulletin/posts.ndjson 167 ``` 168 169 ### Formato 170 171 Uma linha JSON por post, por exemplo: 172 173 ```json 174 {"id":"20260519T120000Z-pablo-a1b2c3","username":"pablo","created_at":"2026-05-19T12:00:00Z","body":"Hoje configurei meu gopher"} 175 ``` 176 177 O username em `post` vem sempre do utilizador Unix actual (`getpwuid`); não se aceita username por argumento. 178 179 ### Permissões 180 181 O directório global precisa permitir escrita pelos membros. Sugestão operacional (ajuste o grupo se o vosso não for `runv`): 182 183 ```bash 184 sudo mkdir -p /var/lib/runv/bulletin 185 sudo touch /var/lib/runv/bulletin/posts.ndjson 186 sudo touch /var/lib/runv/bulletin/posts.lock 187 sudo chgrp -R runv /var/lib/runv/bulletin 188 sudo chmod 2775 /var/lib/runv/bulletin 189 sudo chmod 664 /var/lib/runv/bulletin/posts.ndjson /var/lib/runv/bulletin/posts.lock 190 ``` 191 192 Sem permissão de escrita, `post` mostra mensagem clara — **não** há fallback para `/tmp`. 193 194 --- 195 196 ## Instalação 197 198 No servidor (clone em `REPO`): 199 200 ```bash 201 cd REPO/tools 202 sudo python3 tools.py --dry-run --verbose 203 sudo python3 tools.py 204 ``` 205 206 Verificar: 207 208 ```bash 209 which runv-profile runv-finger runv-who runv-bulletin runv-email-alias runv-admin-email-alias 210 ls -l /usr/local/share/runv/lib/runv_community.py /usr/local/share/runv/lib/runv_email_aliases.py 211 ``` 212 213 Novas contas recebem modelos em `/etc/skel` (`.plan`, `.project`, `.runv/profile.json`) após `tools.py`. 214 215 --- 216 217 ## Testes manuais rápidos 218 219 ```bash 220 runv-profile init 221 runv-profile show 222 runv-finger "$USER" 223 runv-who 224 runv-who --json 225 226 mkdir -p /tmp/runv-bulletin-test 227 export RUNV_BULLETIN_PATH=/tmp/runv-bulletin-test/posts.ndjson 228 runv-bulletin post "primeiro teste do mural" 229 runv-bulletin 230 runv-bulletin --json 231 ``` 232 233 Sintaxe Python (repo): 234 235 ```bash 236 cd REPO 237 python3 -m compileall -q tools 238 ``` 239 240 --- 241 242 ## `runv-email-alias` 243 244 ### O que faz 245 246 Permite pedir um alias de email fixo `username@runv.club` que, após aprovação admin, deve encaminhar para um email externo. 247 248 - Não cria mailbox no servidor. 249 - Não activa o encaminhamento automaticamente. 250 - O membro só indica o email de destino; o nome do alias segue o username Unix. 251 252 ### Exemplos 253 254 Na sessão SSH do **membro** (sem `sudo`): 255 256 ```bash 257 runv-email-alias request usuario@example.org 258 runv-email-alias status 259 runv-email-alias cancel 260 ``` 261 262 Requisito: o utilizador tem de pertencer ao grupo `runv-members` (contas criadas com `create_runv_user.py`). Contas só de administração do servidor não usam este comando. 263 264 Política, ficheiros em `/var/lib/runv/` e setup: [08-email.md](08-email.md). 265 266 --- 267 268 ## `runv-admin-email-alias` 269 270 ### O que faz 271 272 Comando **root** para listar pedidos, aprovar ou rejeitar aliases, e actualizar `email-aliases.json` localmente. Não chama Mailgun nem configura DNS. 273 274 ### Exemplos 275 276 ```bash 277 sudo runv-admin-email-alias pending 278 sudo runv-admin-email-alias list 279 sudo runv-admin-email-alias approve pablo 280 sudo runv-admin-email-alias sync 281 sudo runv-admin-email-alias reject pablo --reason "email destino inválido" 282 ``` 283 284 Sync Postfix (membros, não Mailgun): [08-email.md](08-email.md) e `scripts/admin/discover_mail_stack.py`. 285 286 Setup inicial da fila e permissões: 287 288 ```bash 289 sudo python3 scripts/admin/setup_email_aliases.py 290 sudo python3 scripts/admin/setup_email_aliases.py --add-existing-users 291 ``` 292 293 --- 294 295 ## Próximos passos futuros 296 297 Possíveis evoluções (fora do âmbito actual): 298 299 - `runv-admin bulletin hide/delete` (moderação); 300 - feed público do mural no site; 301 - integração com Garden / Gotchi; 302 - backfill admin para membros existentes. 303 304 Próximo: [15-glossary-and-reference.md](15-glossary-and-reference.md).