refactor(types): introduce strong typing for domain concepts

[JacksonFergusonDev]

Summary

Refactor raw primitive types (str, int, bool, primitive tuples) used throughout the codebase into strongly typed domain representations. This eliminates primitive obsession and enhances static type safety across git operations, configuration parsing, background daemon workflows, telemetry, and CLI interactions.

Key Changes

• New Module git_pulsar.types:

  • Enums (enum.StrEnum):
    • Preset: Fixed set of backup intensity presets (paranoid, aggressive, balanced, lazy).
    • RepoStatus: Operational state of repositories (Active, Paused, Missing, Error, Unknown).
    • DaemonStatus: Daemon process status (Active (Running), Active (Idle), Stopped).
    • SkipReason: Explicit reasons for skipping backup iterations (Path missing, Paused by user, System under load, Battery critical).
    • ConfigSection: Valid configuration sections (core, daemon, limits, files).
  • Domain Identifiers & Units (typing.NewType):
    • MachineId: Unique persistent machine UUID string.
    • MachineName: User-assigned human-readable machine name.
    • MachineSlug: Composite machine identifier ({name}--{short_id}).
    • GitRef: Namespaced Git reference string.
    • BranchName: Git branch name.
    • GitOID: Generic 40-character Git object identifier.
    • CommitSHA: Derived commit object identifier.
    • TreeSHA: Derived tree object identifier.
    • Seconds: Time intervals in seconds.
    • ByteSize: File and log sizes in bytes.
  • Structured Domain Returns (typing.NamedTuple / dataclass):
    • BatteryStatus: Contains percent: int and is_plugged: bool with full tuple unpacking backward compatibility.
    • DiffStat: Contains files_changed: int, insertions: int, deletions: int.
    • DriftState: Contains last_check_ts: float, warned_remote_ts: int.
    • RemoteDriftResult: Contains drift_detected: bool, newest_ts: int, newest_machine: MachineSlug | str, warning: str.
    • BackupRefInfo: Strongly-typed dataclass for parsed backup refs.

• Refactored Modules:

  • git_pulsar/config.py: Integrated Preset, ConfigSection, ByteSize, and Seconds.
  • git_pulsar/git_wrapper.py: Updated GitRepo methods (current_branch, write_tree, commit_tree, diff_shortstat, list_refs, rev_parse) with domain types.
  • git_pulsar/system.py: Updated platform strategies and identifier helpers to return BatteryStatus, MachineId, MachineSlug, and MachineName.
  • git_pulsar/ops.py: Updated reference parsing, remote drift detection, and state persistence with domain types.
  • git_pulsar/daemon.py: Updated skip conditions and reference handlers with SkipReason and GitRef.
  • git_pulsar/cli.py: Integrated DaemonStatus, RepoStatus, and GitRef for status and listing views.
  • git_pulsar/__init__.py: Exported types module.

• Tests & Verification:

  • Added tests/test_types.py covering enums, newtypes, and structured data classes.
  • All 179 unit tests pass.
  • Strict MyPy type checking passes across all 18 source and test files.
  • Ruff linter and formatter pass without errors.