feat: extended file attributes (RFC 0004)

[rmanibus]

Summary

Implement RFC 0004 by adding extended file attribute and POSIX metadata capture in backup scans, with platform-aware handling and CLI controls.

What Changes

• Extend core.FileMeta with metadata fields:
  • mode, uid, gid, btime, flags, xattrs
• Extend core.SourceInfo with fs_type.
• Local source:
  • add metadata collection helpers for Darwin/Linux/Unix + stub fallback
  • support namespace filtering for xattrs
• SFTP source:
  • populate mode/uid/gid from SFTP attrs when available
• CLI:
  • add backup flags -skip-mode, -skip-flags, -skip-xattrs, -xattr-namespaces
  • update completion and user-facing help/docs
• Engine/tests/docs:
  • backup scan behavior and tests updated
  • RFC and spec/user-guide docs updated

Tracking

• Story / epic: RFC 0004: Epic / Tracking issue for extended file attributes #95
• RFC: rfcs/0004-extended-file-attributes.md
• Milestone: RFC 0004: Extended file attributes

Notes

• Branch was rebased onto latest main.
• Behavior is best-effort by platform/filesystem; unsupported metadata paths fall back safely.

[codecov]

Codecov Report

❌ Patch coverage is 80.82192% with 42 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/source/local_source_xattr_linux.go	36.73%	27 Missing and 4 partials ⚠️
pkg/source/local_source_xattr_unix.go	83.87%	5 Missing and 5 partials ⚠️
cmd/cloudstic/cmd_auth.go	0.00%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Implements RFC 0004 by extending snapshot file metadata to include POSIX attributes (mode/uid/gid/btime/flags), extended attributes (xattrs), and a filesystem/source type (fs_type) across local/SFTP/cloud sources, with CLI controls and updated docs/tests.

Changes:

• Extend core models (core.FileMeta, core.SourceInfo) to store extended POSIX metadata, xattrs, and fs_type.
• Add local (Linux/macOS) best-effort collectors for btime/flags/xattrs (+ stubs elsewhere) and wire them into local scans; populate mode/uid/gid from SFTP attrs.
• Add CLI flags to control metadata collection and update completions, docs, and engine equality/tests accordingly.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
rfcs/0004-extended-file-attributes.md	Marks RFC as implemented; adds notes for future cloud metadata mapping.
pkg/source/sftp_source.go	Adds FsType and extracts mode/uid/gid from SFTP FileStat.
pkg/source/onedrive.go	Populates FsType for OneDrive sources.
pkg/source/local_source_xattr_unix.go	Implements Linux/macOS extended metadata + xattr listing/reading.
pkg/source/local_source_xattr_test.go	Adds Linux/macOS tests for extended metadata + xattr filtering behavior.
pkg/source/local_source_xattr_stub.go	Provides no-op implementations for unsupported platforms.
pkg/source/local_source_xattr_linux.go	Linux statx-based btime, ioctl flags, and filesystem type detection.
pkg/source/local_source_xattr_darwin.go	macOS btime/flags/fs type detection via stat/statfs.
pkg/source/local_source.go	Wires extended metadata collection into local walk and exposes options/FsType.
pkg/source/gdrive.go	Populates FsType for Google Drive sources.
internal/engine/backup_scan_test.go	Adds tests validating equality semantics for extended fields and helpers.
internal/engine/backup_scan.go	Extends metadata equality to include mode/uid/gid/btime/flags/xattrs.
internal/core/models.go	Adds extended metadata + xattrs to FileMeta and fs_type to SourceInfo.
internal/core/core_test.go	Adds tests for JSON omitempty and hash stability with xattrs.
go.sum	Cleans up sums after module dependency adjustments.
go.mod	Promotes/adds dependencies needed by the updated code paths.
docs/user-guide.md	Documents new CLI flags and extended metadata behavior for local/SFTP.
docs/spec.md	Updates snapshot format examples/field descriptions (mode/uid/gid/btime/flags/xattrs, fs_type).
cmd/cloudstic/usage.go	Adds the new backup flags to usage output.
cmd/cloudstic/completion.go	Updates shell completions to include the new backup flags.
cmd/cloudstic/cmd_backup_test.go	Adds CLI/initSource tests for extended local-source options.
cmd/cloudstic/cmd_backup.go	Adds new backup flags and threads options into local source initialization.
cmd/cloudstic/cmd_auth.go	Updates auth flows to call the new initSource signature.

---

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

[rmanibus]

Addressed the Copilot review comments on PR #78 in commit 35cb3e4.

What changed:

• Aligned skip-flags wording with behavior:
  • cmd flag/help now says "Skip file flags collection"
  • usage/completion/docs updated to match
  • WithSkipFlags comment updated in local source options
• Hardened xattr namespace parsing in backup source init:
  • trims whitespace
  • drops empty prefixes (so empty entries no longer match all xattrs)
  • only applies WithXattrNamespaces when at least one prefix remains
  • added TestParseXattrNamespacePrefixes
• Switched xattr reads to non-dereferencing syscalls:
  • Llistxattr / Lgetxattr (instead of Listxattr / Getxattr)
  • avoids following symlink targets while collecting xattrs
• Fixed docs examples and consistency:
  • local source examples now use local:/path syntax
  • clarified SFTP metadata sentence to avoid contradiction

Validation run:

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