feat: add direct-to-directory restore format (RFC 0006)

[rmanibus]

Summary

• Add step-1 support for direct filesystem restore via cloudstic restore -format dir -output <directory>.
• Keep existing ZIP restore behavior intact while adding format auto-detection (.zip -> zip, otherwise dir).
• Add engine support through RestoreManager.RunToDir and expose it via Client.RestoreToDir.
• Update restore CLI/completions/help and user guide for the new restore format.

Scope notes

• This is step 1 of RFC 0006 and intentionally does not include extended metadata replay (xattrs/ownership/flags).
• Path filtering and dry-run continue to work for both formats.

Testing

• go test -count=1 ./internal/engine -run 'TestRestoreManager_Run|TestRestoreManager_RunToDir|TestRestoreManager_PathFilter'
• go test -count=1 ./cmd/cloudstic -run 'TestPrintRestoreSummary|TestResolveRestoreFormat|TestCompletionBash|TestCompletionZsh|TestCompletionFish'
• go test -count=1 ./...
• golangci-lint run ./...

Refs #104

[codecov]

Codecov Report

❌ Patch coverage is 69.58763% with 59 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/engine/restore.go	67.33%	25 Missing and 24 partials ⚠️
cmd/cloudstic/cmd_restore.go	85.71%	2 Missing and 2 partials ⚠️
cmd/cloudstic/usage.go	0.00%	4 Missing ⚠️
client.go	71.42%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR adds step-1 support for restoring snapshots directly into a filesystem directory (cloudstic restore -format dir -output <directory>), while preserving the existing ZIP restore behavior and adding output-based format auto-detection.

Changes:

• Introduces a RestoreWriter abstraction in the engine and implements both ZIP and filesystem writers.
• Adds Client.RestoreToDir and CLI -format handling (explicit zip|dir plus auto-detection from -output).
• Updates tests (unit + e2e), CLI usage text, completions, and user guide to cover the new restore mode.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
internal/engine/restore.go	Refactors restore to use a writer abstraction; adds filesystem restore writer and path hardening helper.
internal/engine/restore_test.go	Updates existing tests for ZIP writer and adds coverage for directory restore + secure path handling.
client.go	Wraps existing restore in ZIP writer and adds RestoreToDir API.
cmd/cloudstic/client_iface.go	Extends CLI client interface with RestoreToDir.
cmd/cloudstic/cmd_restore.go	Adds -format flag, format resolution, and routes to dir restore when requested.
cmd/cloudstic/cmd_restore_test.go	Updates summary assertions and adds tests for restore format resolution.
cmd/cloudstic/stub_client_test.go	Extends stub client to satisfy new interface method for tests.
cmd/cloudstic/completion.go	Updates bash/zsh completions to include -format and -path for restore.
cmd/cloudstic/usage.go	Updates restore help text and examples for dir format.
docs/user-guide.md	Documents ZIP vs dir restore, auto-detection, and updated dry-run wording.
e2e/e2e_test.go	Adds end-to-end coverage for direct-to-directory restore and partial dir restore.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rmanibus]

Addressed Copilot review feedback in commit 4bd4593.

• Updated stale comments in restore engine (WithRestoreDryRun, RestoreManager).
• Added guard for nil RestoreWriter in non-dry-run restore path.
• Hardened fsRestoreWriter against symlink traversal by rejecting symlink components under output root before writes/mkdir.
• Added CLI validation to reject empty -output values in restore format resolution.

Added/updated tests:

• TestResolveRestoreFormat (empty output case)
• TestRestoreManager_Run_NilWriter
• TestFSRestoreWriter_RejectsSymlinkedPathComponent\n\n

Validation run:

• go test -count=1 ./...\n- golangci-lint run ./...