Skip to content

Commit 9ba5e48

Browse files
insigninsign
committed
Merge branch 'v4'
# Conflicts: # src/Rclone.php # tests/Unit/LocalProviderTest.php
2 parents cc47191 + bd69d56 commit 9ba5e48

70 files changed

Lines changed: 7848 additions & 4083 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/phpunit.yml‎

Lines changed: 39 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,66 @@
1-
name : PHPUnit Test
1+
name : CI
22

33
on :
44
push :
5-
branches: [ "main" ]
5+
branches: [ "main", "v4" ]
66
pull_request:
77
branches: [ "main" ]
88

99
permissions:
1010
contents: read
1111

1212
jobs :
13-
test:
13+
analyse:
14+
name: Static Analysis
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Set up PHP
19+
uses: shivammathur/setup-php@v2
20+
with:
21+
php-version: '8.4'
22+
- name: Install dependencies
23+
run : composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
24+
- name: Run PHPStan
25+
run : composer run-script analyse
1426

27+
format:
28+
name: Code Style
1529
runs-on: ubuntu-latest
30+
steps:
31+
- uses: actions/checkout@v4
32+
- name: Set up PHP
33+
uses: shivammathur/setup-php@v2
34+
with:
35+
php-version: '8.4'
36+
- name: Install dependencies
37+
run : composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
38+
- name: Check code style
39+
run : composer run-script format-check
1640

17-
steps :
18-
-
19-
name: Set up PHP
41+
test:
42+
name: Tests
43+
runs-on: ubuntu-latest
44+
needs: [analyse, format]
45+
steps:
46+
- uses: actions/checkout@v4
47+
- name: Set up PHP
2048
uses: shivammathur/setup-php@v2
2149
with:
2250
php-version: '8.4'
23-
-
24-
name: Setup Rclone
51+
- name: Setup Rclone
2552
uses: AnimMouse/setup-rclone@main
26-
27-
-
28-
uses: actions/checkout@v4
29-
30-
-
31-
name: Validate composer.json and composer.lock
53+
- name: Validate composer.json and composer.lock
3254
run : composer validate --strict
33-
34-
-
35-
name: Cache Composer packages
55+
- name: Cache Composer packages
3656
id : composer-cache
3757
uses: actions/cache@v4
3858
with:
3959
path: vendor
4060
key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
4161
restore-keys: |
4262
${{ runner.os }}-php-
43-
44-
-
45-
name: Install dependencies
63+
- name: Install dependencies
4664
run : composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
47-
48-
-
49-
name: Run test suite
65+
- name: Run test suite
5066
run : composer run-script test-local

‎AGENTS.md‎

Lines changed: 144 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,55 +2,57 @@
22

33
**IMPORTANTE:** Ao iniciar qualquer sessão, leia TODOS os arquivos:
44

5-
| Arquivo | Conteúdo |
6-
| -------------- | -------------------------------- |
7-
| @./CODEBASE.md | Mapa do código |
8-
| @./ADR.md | Decisões arquiteturais |
9-
| @./README.md | Visão geral, instalação e uso |
5+
| Arquivo | Conteúdo |
6+
| -------------- | ----------------------------- |
7+
| @./CODEBASE.md | Mapa do código |
8+
| @./ADR.md | Decisões arquiteturais |
9+
| @./README.md | Visão geral, instalação e uso |
1010

1111
As regras deste arquivo são **obrigatórias**.
1212

1313
---
1414

1515
## Referência Rápida
1616

17-
| Campo | Valor |
18-
| --------------- | ------------------------------ |
19-
| **Nome** | Flyclone |
20-
| **Package** | `verseles/flyclone` |
21-
| **PHP** | >= 8.4 (obrigatório) |
22-
| **Repositório** | github.com/verseles/flyclone |
23-
| **Licença** | CC-BY-NC-SA-4.0 |
17+
| Campo | Valor |
18+
| --------------- | ---------------------------- |
19+
| **Nome** | Flyclone |
20+
| **Package** | `verseles/flyclone` |
21+
| **PHP** | >= 8.4 (obrigatório) |
22+
| **Repositório** | github.com/verseles/flyclone |
23+
| **Licença** | CC-BY-NC-SA-4.0 |
2424

2525
---
2626

2727
## Dependências
2828

29-
| Dependência | Obrigatória | Notas |
30-
| ----------------- | ----------- | ---------------------------------- |
31-
| PHP 8.4+ | Sim | Property hooks são utilizados |
32-
| rclone | Sim | Binário deve estar no PATH |
33-
| Composer | Sim | Gerenciamento de dependências |
34-
| podman-compose | Para testes | Containers SFTP, MinIO, FTP |
29+
| Dependência | Obrigatória | Notas |
30+
| -------------- | ----------- | ----------------------------- |
31+
| PHP 8.4+ | Sim | Property hooks são utilizados |
32+
| rclone | Sim | Binário deve estar no PATH |
33+
| Composer | Sim | Gerenciamento de dependências |
34+
| podman-compose | Para testes | Containers SFTP, MinIO, FTP |
3535

3636
---
3737

3838
## Comandos
3939

4040
### Make
41-
| Comando | Descrição |
42-
| ----------------- | ------------------------------------------------ |
43-
| `make test` | Testes rápidos (extra_commands, upload_download) |
44-
| `make test-offline` | Testes completos com containers |
45-
| `make init` | `composer install` |
46-
| `make tog` | Gera documentação para AI |
41+
42+
| Comando | Descrição |
43+
| ------------------- | ------------------------------------------------ |
44+
| `make test` | Testes rápidos (extra_commands, upload_download) |
45+
| `make test-offline` | Testes completos com containers |
46+
| `make init` | `composer install` |
47+
| `make tog` | Gera documentação para AI |
4748

4849
### Composer
49-
| Comando | Descrição |
50-
| ---------------------------- | ---------------------------- |
51-
| `composer test` | Todos os testes |
52-
| `composer test-local` | Apenas LocalProvider (CI) |
53-
| `composer run-script test-offline` | Testes offline completos |
50+
51+
| Comando | Descrição |
52+
| ---------------------------------- | ------------------------- |
53+
| `composer test` | Todos os testes |
54+
| `composer test-local` | Apenas LocalProvider (CI) |
55+
| `composer run-script test-offline` | Testes offline completos |
5456

5557
---
5658

@@ -103,9 +105,12 @@ cp .env.example .env
103105

104106
### Web Search
105107

106-
11. **Use web search para:**
107-
- Confirmar métodos eficientes/modernos
108-
- Resolver erros quando ficar preso
108+
11. **Use web search com FREQUÊNCIA:**
109+
- Antes de implementar: confirmar abordagem moderna/eficiente
110+
- Ao encontrar erro: pesquisar soluções antes de tentar fixes aleatórios
111+
- Ao ficar incerto: pesquisar ao invés de assumir
112+
- Documentação oficial: usar context7 ou busca direta
113+
- **Mínimo 2-3 pesquisas por action complexa**
109114
- Aguardar 1 segundo entre pesquisas (rate limit)
110115

111116
### Notificações
@@ -129,7 +134,7 @@ namespace Verseles\Flyclone\Providers;
129134
class MyCloudProvider extends Provider
130135
{
131136
protected string $provider = 'mycloud';
132-
137+
133138
// Se não suporta pastas vazias (como S3):
134139
protected bool $dirAgnostic = true;
135140
}
@@ -177,11 +182,112 @@ try {
177182

178183
## Docker Compose Services
179184

180-
| Service | Porta | Usuário/Senha |
181-
| ------- | ----- | ----------------------- |
182-
| sftp | 2222 | Ver docker-compose.yml |
183-
| s3 | 9000 | minioadmin/minioadmin |
184-
| ftp | 2121 | Ver docker-compose.yml |
185+
| Service | Porta | Usuário/Senha |
186+
| ------- | ----- | ---------------------- |
187+
| sftp | 2222 | Ver docker-compose.yml |
188+
| s3 | 9000 | minioadmin/minioadmin |
189+
| ftp | 2121 | Ver docker-compose.yml |
190+
191+
---
192+
193+
## Execução de Roadmap
194+
195+
O projeto utiliza o arquivo `ROADMAP.md` para gerenciar tarefas de longo prazo. Siga estas diretrizes para manter a execução lúcida e focada.
196+
197+
### Estado Atual do Projeto
198+
199+
| Branch | Versão | Status | Ação do Agent |
200+
| ------ | ------ | ---------------------- | ----------------------------- |
201+
| `main` | v3.x | Estável | Apenas hotfixes críticos |
202+
| `v4` | v4.0 | **EM DESENVOLVIMENTO** | Todo trabalho do roadmap aqui |
203+
204+
**⚠️ IMPORTANTE:** Ao iniciar sessão para trabalhar no roadmap:
205+
206+
1. `git checkout v4` - Garantir que está na branch correta
207+
2. `cat roadmap/roadmap.md` - Ver estado atual e próximas actions
208+
3. Escolher UMA action pendente e marcar `in_progress`
209+
210+
### Tags e Milestones
211+
212+
| Tag Pattern | Quando Criar | Milestone |
213+
| ---------------- | ------------------------------------------- | --------- |
214+
| `v4.0.0-alpha.N` | Após completar Feature 1 (Core Refactoring) | 1 |
215+
| `v4.0.0-beta.N` | Após completar Feature 2 (Security & DX) | 2 |
216+
| `v4.0.0-rc.N` | Após completar Feature 3 (Polish & Release) | 3 |
217+
| `v4.0.0` | Merge para main + release final | - |
218+
219+
### Antes de Iniciar uma Action
220+
221+
1. **Ler o roadmap.** para entender o contexto geral e identificar dependências.
222+
223+
2. **Ler apenas arquivos necessários.** Não carregar todo o codebase - apenas o que a action específica precisa.
224+
225+
3. **Planejar antes de codar.** Analisar arquivos relevantes e criar um plano mental ANTES de escrever código.
226+
227+
4. **Verificar actions in_progress.** Se outra action está em andamento, NÃO modificar arquivos relacionados a ela.
228+
229+
5. **Marcar in_progress.** Atualize o roadmap assim que iniciar trabalho
230+
231+
### Durante a Execução
232+
233+
6. **Foco estrito.** Trabalhar APENAS na action atual. Não refatorar código fora do escopo.
234+
235+
7. **Escopo mínimo.** Se encontrar problemas fora do escopo, documentar em nota mas NÃO corrigir.
236+
237+
8. **Testar incrementalmente.** Rodar `make test` após cada mudança significativa, não apenas no final.
238+
239+
9. **Commits atômicos.** Cada commit deve representar um passo lógico completo da action.
240+
241+
10. **Atualizar notas.** Atualize roadmap com progresso significativo.
242+
243+
### Ao Concluir uma Action
244+
245+
11. **Verificar completude.** Todos os critérios da action foram atendidos?
246+
247+
12. **Testes passando.** `make test` deve passar antes de marcar como completed.
248+
249+
13. **Atualizar documentação.** Se a action afeta CODEBASE.md ou ADR.md, atualizar agora.
250+
251+
14. **Commit descritivo.** Mensagem referenciando a action: `feat(1.03): Extract StatsParser class`
252+
253+
15. **Marcar completed.** Atualize roadmap alterando status e adicionando nota com resumo.
254+
255+
16. **Limpar contexto.** Antes da próxima action, descartar leituras de arquivos não mais necessários.
256+
257+
### Bugs Encontrados Durante Execução
258+
259+
17. **Sempre corrigir bugs.** Não acumular dívida técnica.
260+
261+
| Momento | Ação |
262+
| ----------------------- | --------------------------------------------------- |
263+
| ANTES de iniciar action | Commit separado (`fix: ...`), depois iniciar action |
264+
| DURANTE a action | Incluir no commit da action, documentar na nota |
265+
266+
18. **Documentar na nota do roadmap:** `"Completed. Also fixed: [descrição breve]"`
267+
268+
### Prevenindo Alucinação e Drift
269+
270+
19. **Checkpoint mental periódico.** Verifique o roadmap com frequência.
271+
272+
20. **Antes de cada commit:** Verificar se as mudanças correspondem à action descrita.
273+
274+
21. **Na dúvida, reler.** Nunca assumir - sempre consultar ROADMAP/ADR/CODEBASE.
275+
276+
22. **Web search frequente.** Pesquisar antes de implementar, ao encontrar erros, quando incerto.
277+
278+
### Prevenindo Drift de Contexto
279+
280+
- **Uma action por sessão** é o ideal. Se múltiplas, são do mesmo milestone.
281+
- **Subagentes para exploração.** Usar `explore` para investigar código sem poluir contexto principal.
282+
- **Notas como memória.** As notas do roadmap servem como memória entre sessões.
283+
- **Reler roadmap** no início de cada nova sessão para reestabelecer contexto.
284+
285+
### Quando Parar e Pedir Ajuda
286+
287+
- Action está demorando mais que o esperado (> 3 tentativas de fix)
288+
- Descobriu que a action precisa ser dividida em sub-actions
289+
- Encontrou conflito com outra action in_progress
290+
- Decisão arquitetural significativa não coberta no ADR.md
185291

186292
---
187293

‎CHANGELOG.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
## [4.0.0] - 2025-01-XX
11+
12+
### Added
13+
14+
#### Feature 1: Core Refactoring (alpha)
15+
- Extracted `ProcessManager` class - binary detection, process execution, error mapping
16+
- Extracted `CommandBuilder` class - rclone command and environment variable construction
17+
- Extracted `StatsParser` class - transfer statistics parsing from rclone output
18+
- Extracted `ProgressParser` class - real-time progress parsing
19+
- Fixed `CryptProvider` - now fully functional with all tests passing
20+
- Fixed `UnionProvider` - now fully functional with all tests passing
21+
- Added `ConfigurationTest` - 13 tests covering configuration behavior
22+
- Added `EdgeCasesTest` - 13 tests covering edge cases and special characters
23+
24+
#### Feature 2: Security & DX (beta)
25+
- Added `SecretsRedactor` - automatic redaction of sensitive data in errors and logs
26+
- Added `RetryHandler` - exponential backoff retry mechanism for transient failures
27+
- Added `FilterBuilder` - fluent API for include/exclude patterns
28+
- Added `Logger` - structured logging with optional debug mode
29+
- Added `CredentialWarning` exception for plaintext credential detection
30+
- Added `healthCheck()` method for provider connectivity verification
31+
- Added `dryRun()` / `isDryRun()` for simulation mode
32+
- Added `withRetry()` / `retry()` for configurable retry behavior
33+
- Added `withFilter()` / `filter()` / `clearFilter()` for filtering
34+
- Added `getLastCommand()` / `getLastEnvs()` for debugging
35+
- Added `isRetryable()` and `getContext()` to exceptions
36+
- Added per-operation timeout configuration
37+
- Added `Feature2Test` - 28 tests for security and DX features
38+
39+
#### Feature 3: Polish & Release (rc)
40+
- Integrated PHPStan at level 5 with CI
41+
- Integrated Laravel Pint (PSR-12) with CI
42+
- Added `bisync()` - bidirectional synchronization
43+
- Added `md5sum()` - MD5 checksums for files
44+
- Added `sha1sum()` - SHA1 checksums for files
45+
- Added `listRemotes()` - list configured remotes (static)
46+
- Added `configFile()` - get config file path (static)
47+
- Added `configDump()` - get config as JSON (static)
48+
- Formatted entire codebase with `declare(strict_types=1)`
49+
50+
### Changed
51+
- Rclone class refactored to use extracted components (~1200 lines reduced)
52+
- Migrated from docker-compose to podman-compose
53+
- CI workflow now runs PHPStan and Pint before tests
54+
- All exceptions now support context and retryable checking
55+
56+
### Fixed
57+
- Race condition in `guessBin()` method
58+
- Input validation in `obscure()` method
59+
- Edge case in `formatBytes()` for zero/negative values
60+
- JSON type validation in `ls()` method
61+
- Buffer handling in ProgressParser for fragmented output
62+
63+
### Removed
64+
- Unused `resetProgress()` method
65+
- Unused `OBSCURED_PATTERN` constant
66+
67+
## [3.x] - Previous Versions
68+
69+
- Transfer operations return detailed statistics object
70+
- Progress tracking improvements
71+
- Initial provider implementations
72+
73+
[Unreleased]: https://github.com/verseles/flyclone/compare/v4.0.0...HEAD
74+
[4.0.0]: https://github.com/verseles/flyclone/compare/v3.0.0...v4.0.0

0 commit comments

Comments
 (0)