Feature/diff status

.github/scripts/README.md

@@ -0,0 +1,119 @@
+# 📜 Changelog
+
+DotCtl uses Git tags to maintain versioned changelogs. Each release is tied to a Git tag (e.g., `v1.1.0`), and commits between tags are grouped automatically.
+
+## 🧾 Manual vs Generated Changelog
+
+You can maintain the changelog in two ways:
+
+- **Manual (recommended for releases):** curated, clean, user-facing notes
+- **Generated (for reference/debugging):** derived from Git history
+
+---
+
+## 🚀 Generate Changelog Automatically
+
+DotCtl includes helper scripts to generate changelog files from Git history.
+
+### 1. Tag-based changelog (recommended)
+
+```sh
+./changelog_by_tag.sh > CHANGELOG.generated.md
+```
+
+This groups commits under each Git tag:
+
+- `v1.0.0`
+- `v1.0.1`
+- etc.
+
+Best for release history.
+
+---
+
+### 2. Full commit history changelog
+
+```sh
+./changelog.sh > CHANGELOG.full.md
+```
+
+Generates a linear commit-based log using:
+
+- commit hash
+- date
+- message
+
+Useful for debugging or audit trails.
+
+---
+
+## 🧪 Alternative Git Commands
+
+You can also generate changelog data manually using Git:
+
+```sh
+git log --pretty=format:"%h | %ad | %s" --date=short
+```
+
+```sh
+git log --merges --oneline
+```
+
+```sh
+git log --decorate --pretty=format:"%h | %ad | %d | %s" --date=short
+```
+
+---
+
+## 📌 Versioning Strategy
+
+DotCtl follows **semantic versioning**:
+
+```txt
+MAJOR.MINOR.PATCH
+```
+
+- **PATCH** → bug fixes (1.1.0 → 1.1.1)
+- **MINOR** → new features (1.1.0 → 1.2.0)
+- **MAJOR** → breaking changes (1.1.0 → 2.0.0)
+
+Example:
+
+- `v1.0.x` → initial stable feature set
+- `v1.1.0` → new commands like `status`, `diff`
+- `v2.0.0` → breaking CLI or config changes
+
+---
+
+## 📅 Date in Changelog?
+
+Dates are optional but recommended for releases:
+
+- Helps track release timeline
+- Useful for users consuming releases via GitHub
+
+Format:
+
+```txt
+# v1.1.0 - 2026-05-23
+```
+
+If you prefer minimal style, you can omit dates and rely on Git tags alone.
+
+---
+
+## 📦 Recommended Practice
+
+For best results:
+
+- Keep **CHANGELOG.md manually curated**
+- Use scripts only to **generate drafts**
+- Only include **user-facing changes**
+- Avoid commit noise (WIP, refactors, internal changes)
+
+---
+
+If you want next step, I can also help you turn this into:
+
+- GitHub Release automation (auto changelog per tag)
+- or a Python CLI command: `dotctl changelog`

.github/scripts/changelog.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "# Recent Changelog"
+echo
+
+git log --pretty=format:"- %h | %ad | %s" --date=short -n 100

.github/scripts/changelog_by_tag.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "# Changelog"
+echo
+
+# Iterate tags in reverse chronological order
+git tag --sort=-creatordate | while read -r tag; do
+  date=$(git log -1 --format=%ad --date=short "$tag")
+
+  echo "## $tag - $date"
+  echo
+
+  # commits in this tag range
+  git log "${tag}^..${tag}" --pretty=format:"- %s" || true
+
+  echo
+  echo
+done

CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+## v1.1.0 - 2026-05-23
+
+**Features**:
+
+- Added `status` command
+- Added drift detection support
+- Added `diff` command
+- Added side-by-side diff rendering
+- Added colored diff output
+- Added short status rendering
+- Added structured status report model
+
+**Fixes**:
+
+- Fixed incorrect file existence detection for permission-restricted files (`Path.exists()` was not sufficient)
+- Improved file stat handling using `os.stat()` / permission-aware checks in status and diff operations
+
+**UX Improvements**:
+
+- Improved CLI icons and symbols
+- Improved human-readable status output
+- Added cleaner sync/drift reporting
+
+**Known Limitations**:
+
+- `sudo` handling currently only applies to the `save` command
+- Some commands may still show limited metadata for restricted files depending on system permissions
+
+## v1.0.9 - 2025-06-25
+
+**Features**:
+
+- Added `--prune` flag to clean stale tracked files
+- Added automatic config cleanup support
+- Added entry cleanup support
+
+**Fixes**:
+
+- Fixed dependency-related issues
+- Fixed path existence handling in data handler
+
+**Improvements**:
+
+- Improved README documentation
+- General code cleanup and refactoring
+
+---
+
+## v1.0.8 - 2025-04-22
+
+**Features**:
+
+- Added improved CLI symbols and status messages
+- Added automatic pull support during save/apply operations
+
+**Fixes**:
+
+- Fixed pull operation for local-only branches
+- Prevented overwriting existing hooks/config during initialization
+
+---
+
+## v1.0.7 - 2025-04-10
+
+**Features**:
+
+- Added interactive hooks support
+- Added `--hooks-timeout` flag for hook execution control
+
+**Fixes**:
+
+- Improved hook error handling
+- Improved shell script execution handling
+
+**Documentation**:
+
+- Added profile workflow diagram
+- Updated README examples and usage docs
+
+---
+
+## v1.0.6 - 2025-04-06
+
+**Features**:
+
+- Added support for creating empty profiles
+- Added profile initialization checkpoints
+- Added hook system:
+  - pre-apply hooks
+  - post-apply hooks
+  - hook failure control flags
+
+**Improvements**:
+
+- Added dynamic props support
+- Improved importer/exporter cleanup
+- Added profile wipe command
+
+**Fixes**:
+
+- Fixed missing templates/packages
+- Fixed missing binary handler
+
+---
+
+## v1.0.5 - 2025-04-03
+
+**Features**:
+
+- Added profile import support
+- Added profile export support
+- Added push support
+- Added apply profile functionality
+
+**Improvements**:
+
+- Refactored git handlers and saver logic
+- Improved initialization workflow
+- Added fetch support for cloud metadata sync
+
+---
+
+## v1.0.4 - 2025-03-26
+
+**Features**:
+
+- Added profile listing
+- Added profile switching
+- Added profile creation
+- Added profile removal
+
+**Improvements**:
+
+- Added handler-based architecture
+- Added detailed profile metadata
+
+**Fixes**:
+
+- Fixed local vs archived profile handling
+- Fixed repository metadata issues
+
+---
+
+## v1.0.3 - 2025-03-12
+
+**Features**:
+
+- Added initialization workflow
+- Added configuration validation
+- Added environment-specific templates
+
+**Fixes**:
+
+- Fixed permission handling issues
+- Fixed workflow and packaging bugs
+
+**Improvements**:
+
+- Refactored configuration initialization
+- Improved logging and typing
+
+---
+
+## v1.0.2 - 2023-01-19
+
+**Initial Public Release**:
+
+- Added first stable `dotctl` implementation
+- Added project structure and packaging
+- Added initial CLI functionality

README.md

@@ -32,9 +32,12 @@ Designed for developers and sysadmins, it supports pre/post hook scripts and is
     - [❌ `remove` / `rm` / `delete` / `del`](#-remove--rm--delete--del)
     - [🧪 `apply`](#-apply)
     - [🔄 `pull`](#-pull)
+    - [🔍 `status`](#-status)
+    - [🔎 `diff`](#-diff)
     - [📤 `export`](#-export)
     - [📥 `import`](#-import)
     - [🔥 `wipe`](#-wipe)
+  - [⚠️ Limitations \& Notes](#️-limitations--notes)
   - [🧑‍💻 Development \& Publishing](#-development--publishing)
     - [Setup Development Environment](#setup-development-environment)
     - [Test the new code](#test-the-new-code)
@@ -521,6 +524,42 @@ dotctl pull
 
 ---
 
+### 🔍 `status`
+
+Inspect the current profile health and detect configuration drift between the repository and local system.
+
+```sh
+dotctl status [--json] [--short]
+```
+
+**Examples:**
+
+```sh
+dotctl status
+dotctl status --short
+dotctl status --json
+```
+
+---
+
+### 🔎 `diff`
+
+Compare tracked files between the repository and local system.
+
+```sh
+dotctl diff [--color] [--side-by-side]
+```
+
+**Examples:**
+
+```sh
+dotctl diff
+dotctl diff --color
+dotctl diff --side-by-side
+```
+
+---
+
 ### 📤 `export`
 
 Export a profile to `.dtsv`.
@@ -585,6 +624,15 @@ dotctl wipe -y
 
 ---
 
+## ⚠️ Limitations & Notes
+
+- Sudo support is currently available only for the `save` command.
+- Commands like `status`, `diff`, `apply`, and others may skip restricted files if permissions are insufficient.
+- Ensure tracked files/directories have proper read permissions before adding them to `dotctl.yaml`.
+- Missing or inaccessible files may appear as drift during `status` or `diff` operations.
+
+---
+
 ## 🧑‍💻 Development & Publishing
 
 ### Setup Development Environment