Add --dry-run flag to CLI and dry_run option to API

[sangampaudel530]

Summary

This PR adds a "dry-run" preview mode to Forklet so users can see which files would be downloaded without creating directories or writing files.

• CLI: adds --dry-run / -n option to forklet download.
• API: adds dry_run: bool support to DownloadRequest.
• Orchestrator: short-circuits after filter step when dry_run is True and returns a DownloadResult-like summary.
• Tests: adds unit test tests/core/test_orchestrator_dry_run.py.

Why this change

• Lets users validate filter patterns, refs, and estimated download size before performing potentially large or destructive downloads.
• Improves safety by avoiding accidental bandwidth/disk use.
• Low-risk change with straightforward behavior and tests.

What Changed

Files changed (high-level)

• forklet/models/download.py
  • Added dry_run: bool = False to DownloadRequest.
• forklet/main.py
  • Added --dry-run / -n click option to download command.
  • Ensure module is executable with python -m forklet.
• forklet/interfaces/cli.py
  • Propagates dry_run into DownloadRequest.
• forklet/core/orchestrator.py
  • Added early-return dry-run path that computes totals and skipped files without writing to disk.
  • Sets _current_result earlier for consistent status endpoints.
• tests/core/test_orchestrator_dry_run.py
  • New test verifying dry_run=True returns the expected summary and does not create files.

Behavior

• When --dry-run is passed, Forklet:
  • resolves repository and ref,
  • retrieves repository tree and applies filters,
  • computes progress totals (total_files, total_bytes),
  • computes skipped files (files that would be skipped because they already exist locally),
  • returns a result with downloaded_files == [] and does NOT create directories or write files.
• CLI prints a concise summary. --verbose increases logging and shows debug lines.

How to test (quick)

1. Activate venv and ensure package installed:

& C:\Users\sanga\Forklet\.venv\Scripts\Activate.ps1
python -m pip install -e .

2. Run the new unit test:

python -m pytest tests/core/test_orchestrator_dry_run.py -q
# Expected: 1 passed

3. Run CLI dry-run preview against a real repo (uses master as ref for TheAlgorithms/Python):

python -m forklet download TheAlgorithms/Python out --ref master --target-paths graphics --dry-run
# Expected: summary shows matched files and "Files: 0 downloaded"

4. If you hit GitHub rate-limit 403, set a token for the session:

$env:GITHUB_TOKEN = 'YOUR_TOKEN'
python -m forklet download TheAlgorithms/Python out --ref master --target-paths graphics --dry-run

Notes for reviewers

• The implementation intentionally avoids creating any filesystem artifacts during dry-run. This keeps the mode safe and easy to reason about.
• return value is a DownloadResult-like object (status set to COMPLETED). If reviewers prefer an explicit was_dry_run flag on the result, I can add that in a follow-up.
• This PR includes a unit test; CI should run the full test suite (the changes are small and tests pass locally).

Checklist for merge

• Code compiles and lints
• Unit tests pass locally (and on CI)

closes #60

[sangampaudel530]

File is not created

Preview of the desired folder

test for proof

@Einswilli kindly see my work and if its is okay kindly merge and give me feedback

[Einswilli]

Looks great!
It'be great to display also file paths in verbose mode.

Thanks for your contributions!

[sangampaudel530]

Looks great! It'be great to display also file paths in verbose mode.

Thanks for your contributions!

added required changes for displaying file paths also in verbose mode.

[sangampaudel530]

Hi @Einswilli I have removed the unnecessary blocks you mentioned above and added the matched_files. block in the download.py
The whole codebase is working properly now

1. Dry run Mode

forklet  download RK1905101/Mini_Python_Projects .\tmp --ref master --target-paths=FLAMES --dry-run

2. Dry run with Verbose mode

forklet -v download RK1905101/Mini_Python_Projects .\tmp --ref master --target-paths=FLAMES --dry-run

[Einswilli]

Thanks this looks cleaner 👍🏾
Great work!