aethel 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0 (2026-04-05)
+
+- Refactor to Repository pattern; add TUI command system with catalog, CLI runner, and tests
+
+## 0.2.6 (2026-04-05)
+
+- Rewrite README with clearer structure and usage examples
+
 ## 0.2.5 (2026-04-05)
 
 - Fix Node.js v25 Proxy invariant violation in withDriveRetry

package/README.md

@@ -5,12 +5,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**Git-style Google Drive sync CLI with an interactive terminal UI.**
+**Git-style Google Drive sync from your terminal.**
 
-Aethel lets you manage a local workspace mirrored to Google Drive using
-familiar commands (`init`, `status`, `diff`, `add`, `commit`, `pull`, `push`)
-and ships with a dual-pane TUI for browsing, uploading, and deleting files
-across local and remote directories.
+Aethel brings a `snapshot → diff → stage → commit` workflow to Google Drive. Track changes on both sides, resolve conflicts explicitly, and keep a full sync history — all without leaving the command line. It also ships with a dual-pane TUI for hands-on file management.
+
+---
 
 ## Install
 
@@ -18,96 +17,89 @@ across local and remote directories.
 npm install -g aethel
 ```
 
-Or install from source:
+<details>
+<summary>Install from source</summary>
 
 ```bash
-git clone https://github.com/aethel/aethel.git
-cd aethel
+git clone https://github.com/CCJ-0617/Aethel.git
+cd Aethel
 npm install
 npm run install:cli   # symlinks `aethel` into ~/.local/bin
 ```
 
-**Requirements:** Node.js >= 18
+</details>
 
-## Release Readiness
+**Requires Node.js >= 18**
 
-- npm package metadata is defined in `package.json`
-- publish contents are restricted through the `files` allowlist
-- local secrets such as `credentials.json` and `token.json` are excluded from Git and npm publish
-- release validation runs with `npm test` and `npm run pack:check`
+## Setup
 
-## GitHub Automation
+1. Create a project in the [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the **Google Drive API**
+3. Create an **OAuth 2.0 Client ID** (Desktop application)
+4. Download the credentials JSON and save it as `credentials.json` in your project root
 
-- `CI`: runs `npm ci`, `npm test`, and `npm run pack:check` on every push and pull request across Node.js 18, 20, and 22
-- `Version & Release`: bumps the version, updates the changelog, creates a GitHub Release, publishes to npm, and publishes to GitHub Packages
-- `Publish GitHub Packages (manual)`: manually publishes the package to GitHub Packages only
-- `Dependabot`: opens weekly dependency update PRs for npm packages and GitHub Actions
+```bash
+aethel auth                    # opens browser, saves token.json
+aethel init --local-path ./workspace --drive-folder <folder-id>
+```
 
-To enable npm trusted publishing, configure a trusted publisher for package `aethel` on npm with:
+> `credentials.json` and `token.json` are local secrets — never commit them.
 
-- provider: GitHub Actions
-- owner: `CCJ-0617`
-- repository: `Aethel`
-- workflow filename: `version.yml`
+## Usage
 
-After trusted publishing works once, disable token-based npm publishing in GitHub Actions and revoke any old npm automation tokens.
+```bash
+aethel status                  # local vs remote changes at a glance
+aethel diff --side all         # detailed file-level diff
+aethel add --all               # stage default suggested actions
+aethel commit -m "sync"        # execute staged operations
 
-## Google Cloud Setup
+aethel pull -m "pull"          # fetch remote changes and apply
+aethel push -m "push"          # push local changes to Drive
+```
 
-1. Create a project in the [Google Cloud Console](https://console.cloud.google.com/).
-2. Enable the **Google Drive API**.
-3. Create an **OAuth 2.0 Client ID** (application type: Desktop).
-4. Download the credentials JSON and save it as `credentials.json` in your
-   project root (or set `GOOGLE_DRIVE_CREDENTIALS_PATH`).
+### Conflict Resolution
 
-Keep `credentials.json` and `token.json` local only. Do not commit them to GitHub.
+When both local and remote change the same path:
 
-## Quick Start
+```bash
+aethel status                  # identify conflicts
+aethel resolve <path> --keep local   # or: remote, both
+aethel commit -m "resolve"
+```
+
+### Deduplication
+
+Multi-device conflicts can leave duplicate folders on Drive:
 
 ```bash
-# Authenticate and verify access
-aethel auth
-
-# Initialize a sync workspace
-aethel init --local-path ./workspace
-
-# Optional: target a specific Drive folder
-aethel init --local-path ./workspace \
-  --drive-folder <folder-id> \
-  --drive-folder-name "My Project"
-
-# Check status and sync
-aethel status
-aethel diff --side all
-aethel add --all
-aethel commit -m "initial sync"
-aethel pull -m "pull"
-aethel push -m "push"
-aethel log -n 10
+aethel dedupe-folders            # dry run — report only
+aethel dedupe-folders --execute  # merge duplicates, trash empties
 ```
 
+Processes deepest-first for single-pass convergence, caches child state to minimize API calls, and runs independent merge groups in parallel.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `auth` | Run OAuth flow, create `token.json`, verify Drive access |
+| `auth` | OAuth flow — creates `token.json`, verifies Drive access |
 | `init` | Initialize a local sync workspace |
-| `status` | Show workspace status (local vs remote changes) |
-| `diff` | Show detailed file differences |
-| `add` | Stage changes for commit |
+| `status` | Show local vs remote changes |
+| `diff` | Detailed file differences |
+| `add` | Stage changes |
 | `reset` | Unstage changes |
 | `commit` | Execute staged sync operations |
-| `pull` | Fetch remote changes and commit |
-| `push` | Stage and push local changes |
-| `log` | Show sync history |
-| `fetch` | Refresh remote state without applying changes |
-| `resolve` | Resolve conflicts by choosing local, remote, or both |
-| `ignore` | List, test, or create `.aethelignore` patterns |
-| `show` | Show a saved snapshot |
+| `pull` | Fetch and apply remote changes |
+| `push` | Push local changes to Drive |
+| `log` | Sync history |
+| `fetch` | Refresh remote state without applying |
+| `resolve` | Resolve conflicts (local / remote / both) |
+| `ignore` | Manage `.aethelignore` patterns |
+| `show` | Inspect a saved snapshot |
 | `restore` | Restore files from the last snapshot |
 | `rm` | Remove local files and stage remote deletion |
 | `mv` | Move or rename local files |
-| `clean` | List and optionally trash/delete accessible Drive files |
+| `clean` | List and optionally trash/delete Drive files |
 | `dedupe-folders` | Detect and merge duplicate remote folders |
 | `tui` | Launch interactive terminal UI |
 
@@ -117,56 +109,36 @@ aethel log -n 10
 aethel tui
 ```
 
-Dual-pane file browser with local filesystem on the left and Google Drive on
-the right.
+Dual-pane file browser — local filesystem on the left, Google Drive on the right.
 
 | Key | Action |
 |-----|--------|
-| `Tab` | Switch focus between Local / Drive pane |
+| `Tab` | Switch panes |
 | `Left` / `Right` | Navigate up / into directories |
-| `u` | Upload selected local file or folder to current Drive directory |
-| `s` | Batch sync local folder contents to current Drive directory |
-| `U` | Upload from a manually entered local path |
+| `u` | Upload selected local file or folder to Drive |
+| `s` | Batch sync local folder to current Drive directory |
+| `U` | Upload from a manually entered path |
 | `n` | Rename selected local item |
 | `x` | Delete selected local item |
 | `Space` | Toggle selection in Drive pane |
 | `t` / `d` | Trash / permanently delete selected Drive items |
 | `/` | Filter by name |
-
-## Deduplication
-
-When duplicate folders accumulate from multi-device conflicts, run:
-
-```bash
-# Dry run — report duplicates without changing anything
-aethel dedupe-folders
-
-# Execute — merge duplicates and trash empty losers
-aethel dedupe-folders --execute
-```
-
-The deduplication engine processes folders deepest-first to guarantee
-single-pass convergence, caches child state in memory to minimize API calls,
-and runs independent merge groups in parallel. Paths matching `.aethelignore`
-are excluded automatically.
+| `f` | Open the commands page and choose a TUI action |
+| `:` | Run any Aethel CLI command inside the TUI |
 
 ## Ignore Patterns
 
-Create a `.aethelignore` file (gitignore syntax) in your workspace root to
-exclude paths from sync and deduplication:
+Create `.aethelignore` (gitignore syntax) in your workspace root — or run `aethel init` to generate a default one.
 
 ```gitignore
 .venv/
 node_modules/
 __pycache__/
 .idea/
-.vscode/
 dist/
 build/
 ```
 
-A default `.aethelignore` is created on `init`.
-
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -177,19 +149,31 @@ A default `.aethelignore` is created on `init`.
 
 ## Architecture
 
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for module structure and data
-flow.
-
-## Publishing
+Aethel uses a **Repository pattern** — a single `Repository` class (`src/core/repository.js`) wraps all core modules and serves as the unified data-access layer for both the CLI and the TUI.
 
-```bash
-npm test
-npm run pack:check
-npm publish
+```
+src/
+├── cli.js                    CLI entry — all handlers use Repository
+├── core/
+│   ├── repository.js         Unified data-access layer
+│   ├── auth.js               OAuth authentication
+│   ├── config.js             Workspace config & state persistence
+│   ├── diff.js               Change detection between states
+│   ├── drive-api.js          Google Drive API wrapper
+│   ├── local-fs.js           Local filesystem operations
+│   ├── remote-cache.js       Short-lived remote file cache
+│   ├── snapshot.js            Local scanning & snapshot creation
+│   ├── staging.js            Stage/unstage operations
+│   ├── sync.js               Execute staged changes
+│   └── ignore.js             .aethelignore pattern matching
+└── tui/
+    ├── app.js                React (Ink) dual-pane component
+    ├── index.js              TUI entry
+    ├── commands.js           CLI command parser for TUI
+    └── command-catalog.js    Available TUI commands
 ```
 
-For a GitHub release, push the tagged version and create a release that matches
-the published npm version.
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed module structure and data flow.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aethel",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Git-style Google Drive sync CLI with interactive TUI",
   "type": "module",
   "license": "MIT",