aethel 0.1.0

package/.env.example

@@ -0,0 +1,2 @@
+GOOGLE_DRIVE_CREDENTIALS_PATH=credentials.json
+GOOGLE_DRIVE_TOKEN_PATH=token.json

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial npm release of the Aethel CLI and Ink TUI
+- Google Drive OAuth authentication and workspace initialization
+- Git-style sync workflow with snapshot, diff, staging, pull, push, and commit
+- Conflict resolution, restore, ignore management, and history inspection
+- Duplicate-folder detection and reconciliation for Google Drive

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aethel Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# Aethel
+
+Git-style Google Drive sync CLI with an interactive terminal UI.
+
+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.
+
+## Install
+
+```bash
+npm install -g aethel
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/aethel/aethel.git
+cd aethel
+npm install
+npm run install:cli   # symlinks `aethel` into ~/.local/bin
+```
+
+**Requirements:** Node.js >= 18
+
+## Release Readiness
+
+- 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`
+
+## GitHub Automation
+
+- `CI`: runs `npm ci`, `npm test`, and `npm run pack:check` on every push and pull request across Node.js 18, 20, and 22
+- `Release`: publishes to npm with trusted publishing when a GitHub Release is published or when the workflow is triggered manually
+- `Dependabot`: opens weekly dependency update PRs for npm packages and GitHub Actions
+
+To enable npm trusted publishing, configure a trusted publisher for package `aethel` on npm with:
+
+- provider: GitHub Actions
+- owner: `CCJ-0617`
+- repository: `Aethel`
+- workflow filename: `release.yml`
+
+After trusted publishing works once, disable token-based publishing in npm package settings and revoke any old npm automation tokens.
+
+## Google Cloud Setup
+
+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`).
+
+Keep `credentials.json` and `token.json` local only. Do not commit them to GitHub.
+
+## Quick Start
+
+```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
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `auth` | Run OAuth flow, create `token.json`, verify 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 |
+| `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 |
+| `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 |
+| `dedupe-folders` | Detect and merge duplicate remote folders |
+| `tui` | Launch interactive terminal UI |
+
+## TUI
+
+```bash
+aethel tui
+```
+
+Dual-pane file browser with local filesystem on the left and Google Drive on
+the right.
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Switch focus between Local / Drive pane |
+| `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 |
+| `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.
+
+## Ignore Patterns
+
+Create a `.aethelignore` file (gitignore syntax) in your workspace root to
+exclude paths from sync and deduplication:
+
+```gitignore
+.venv/
+node_modules/
+__pycache__/
+.idea/
+.vscode/
+dist/
+build/
+```
+
+A default `.aethelignore` is created on `init`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `credentials.json` | Path to OAuth credentials |
+| `GOOGLE_DRIVE_TOKEN_PATH` | `token.json` | Path to cached OAuth token |
+| `AETHEL_DRIVE_CONCURRENCY` | `40` | Max concurrent Drive API requests |
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for module structure and data
+flow.
+
+## Publishing
+
+```bash
+npm test
+npm run pack:check
+npm publish
+```
+
+For a GitHub release, push the tagged version and create a release that matches
+the published npm version.
+
+## License
+
+[MIT](LICENSE)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,237 @@
+# Aethel Architecture
+
+## 1. Project Positioning
+
+Aethel is a synchronization tool that uses Google Drive as its remote storage. It exposes two interface layers:
+
+- CLI: provides a Git-like workflow with `auth`, `init`, `status`, `diff`, `add`, `commit`, `pull`, and `push`.
+- TUI: provides an interactive dual-pane interface for local files and Google Drive.
+
+The core design is not a live mirror between local storage and Drive. Instead, synchronization is managed through a `snapshot + diff + staging + execute` pipeline.
+
+## 2. Module Layers
+
+### 2.1 Entry Layer
+
+- `src/cli.js`
+  - Command-line entry point
+  - Parses commands, assembles workspace state, and invokes core sync capabilities
+- `src/tui/index.js`
+  - Starts the Ink TUI
+- `src/tui/app.js`
+  - Implements dual-pane file browsing, filtering, uploads, deletion, and interactive operations
+
+### 2.2 Core Capability Layer
+
+- `src/core/auth.js`
+  - OAuth authentication
+  - Creates and reads `token.json`
+- `src/core/drive-api.js`
+  - Google Drive API wrapper
+  - Listing, downloading, uploading, deleting, folder creation, and batch operations
+- `src/core/local-fs.js`
+  - Local filesystem operations
+- `src/core/snapshot.js`
+  - Scans local files, computes md5 hashes, and builds snapshots
+- `src/core/diff.js`
+  - Compares snapshot / remote / local state and produces change sets
+- `src/core/staging.js`
+  - Manages the staging area
+- `src/core/sync.js`
+  - Executes staged operations
+- `src/core/config.js`
+  - Manages `.aethel/` state files
+- `src/core/ignore.js`
+  - Manages `.aethelignore`
+- `src/core/remote-cache.js`
+  - Short-lived cache for remote listings
+
+### 2.3 State Storage Layer
+
+After workspace initialization, the project root contains:
+
+```text
+.aethel/
+  config.json
+  index.json
+  .hash-cache.json
+  snapshots/
+    latest.json
+    history/
+```
+
+- `config.json`: sync root configuration
+- `index.json`: currently staged operations
+- `.hash-cache.json`: local file hash cache
+- `snapshots/latest.json`: baseline state after the most recent successful sync
+- `snapshots/history/`: archived older snapshots
+
+## 3. Core Data Flow
+
+```mermaid
+flowchart LR
+    User["User"]
+    CLI["CLI / TUI"]
+    Auth["auth.js"]
+    Config["config.js"]
+    Local["snapshot.js + local-fs.js"]
+    Cache["remote-cache.js"]
+    Drive["drive-api.js"]
+    Diff["diff.js"]
+    Stage["staging.js"]
+    Sync["sync.js"]
+    State[".aethel state"]
+    Google["Google Drive"]
+    Disk["Local Files"]
+
+    User --> CLI
+    CLI --> Auth
+    CLI --> Config
+    CLI --> Local
+    CLI --> Cache
+    CLI --> Drive
+    Local --> Disk
+    Cache --> State
+    Config --> State
+    Drive --> Google
+    Local --> Diff
+    Drive --> Diff
+    State --> Diff
+    Diff --> Stage
+    Stage --> State
+    Stage --> Sync
+    Sync --> Disk
+    Sync --> Google
+    Sync --> State
+```
+
+## 4. Synchronization Model
+
+### 4.1 Baseline
+
+Aethel uses `snapshot` as the shared baseline:
+
+- `snapshot.files`: remote file information from the last sync
+- `snapshot.localFiles`: local file information from the last sync
+
+That means the system does not compare only "local vs remote". It also asks:
+
+- Has Drive changed since the last sync?
+- Has local state changed since the last sync?
+- Did both sides modify the same path?
+
+### 4.2 Diff Categories
+
+`src/core/diff.js` classifies changes as:
+
+- `remote_added`
+- `remote_modified`
+- `remote_deleted`
+- `local_added`
+- `local_modified`
+- `local_deleted`
+- `conflict`
+
+It also provides default suggested actions for each category:
+
+- Drive added/modified -> `download`
+- Drive deleted -> `delete_local`
+- Local added/modified -> `upload`
+- Local deleted -> `delete_remote`
+- Both sides changed the same path -> `conflict`
+
+### 4.3 Execution Model
+
+`commit` is not a Git commit. It executes the synchronization actions currently staged:
+
+1. Read `index.json`
+2. Route each entry by action as `download / upload / delete_local / delete_remote`
+3. Execute local and remote operations
+4. Clear staged entries
+5. Rebuild the snapshot and write the new state to `.aethel/snapshots/latest.json`
+
+## 5. Relationship Between TUI and CLI
+
+Both interfaces share the same core modules. The difference is only the interaction surface:
+
+- CLI is oriented toward predictable, scriptable sync workflows
+- TUI is oriented toward manual inspection, fast operations, and hands-on Drive / Local management
+
+The TUI is not a separate synchronization engine. It directly calls `drive-api.js` and `local-fs.js` for interactive file management.
+
+## 6. Recommended Workflow
+
+### 6.1 Initial Workspace Setup
+
+```bash
+npm install
+npm run auth
+node src/cli.js init --local-path ./workspace --drive-folder <drive-folder-id>
+```
+
+Use this when:
+
+- Starting a new project
+- Creating a new sync root
+- Intentionally syncing only a specific Drive folder
+
+### 6.2 Day-to-Day Sync Workflow
+
+```bash
+node src/cli.js status
+node src/cli.js diff --side all
+node src/cli.js add --all
+node src/cli.js commit -m "sync"
+```
+
+This is the most reasonable standard flow because:
+
+1. `status` gives you the overall state first
+2. `diff` shows details and conflicts
+3. `add --all` stages the default suggested actions
+4. `commit` performs the actual synchronization
+
+This preserves a manual confirmation point and helps avoid pushing a bad state to Drive or overwriting local files by mistake.
+
+### 6.3 When Conflicts Occur
+
+Recommended flow:
+
+1. Run `status` or `diff`
+2. Identify `conflict` entries
+3. Decide explicitly whether to keep local, keep remote, or keep both
+4. Then stage and commit
+
+Why:
+
+- In Aethel, a conflict means both sides changed the same path after the snapshot
+- This should not be resolved automatically because it can cause silent overwrites
+
+### 6.4 When Manual Inspection Is Needed
+
+```bash
+npm run tui
+```
+
+The TUI is useful for:
+
+- Browsing the Drive structure
+- Selecting items and deleting them
+- Uploading files or entire folders directly from local storage
+- Finding files quickly with filters
+
+If the goal is traceable, repeatable synchronization, the CLI workflow should still be the default choice.
+
+## 7. Recommended Practices
+
+- Use a single Drive root folder as the workspace remote root instead of syncing the entire My Drive directly.
+- Run `status` or `diff` before every `commit`.
+- Treat `.aethelignore` as a synchronization boundary control file, not just a UI filter.
+- Keep `.hash-cache.json` for large workspaces to avoid recomputing all md5 values every time.
+- Prefer the TUI or a dry run for risky operations before executing them for real.
+
+## 8. Future Improvements
+
+- Split CLI commands and state transitions into a service layer to reduce how much workflow logic is aggregated in `src/cli.js`.
+- Add documentation for the snapshot schema and index schema.
+- Add automated tests, especially around diff/conflict handling and the sync executor.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "aethel",
+  "version": "0.1.0",
+  "description": "Git-style Google Drive sync CLI with interactive TUI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethel/aethel.git"
+  },
+  "homepage": "https://github.com/aethel/aethel#readme",
+  "bugs": {
+    "url": "https://github.com/aethel/aethel/issues"
+  },
+  "keywords": [
+    "google-drive",
+    "sync",
+    "cli",
+    "tui",
+    "backup",
+    "drive",
+    "file-manager"
+  ],
+  "bin": {
+    "aethel": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/ARCHITECTURE.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "auth": "node src/cli.js auth",
+    "clean": "node src/cli.js clean",
+    "install:cli": "bash scripts/install.sh",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check",
+    "test": "node --test",
+    "tui": "node src/cli.js tui"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "googleapis": "^140.0.1",
+    "ignore": "^7.0.5",
+    "ink": "^5.1.0",
+    "ink-select-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "open": "^10.1.0",
+    "react": "^18.3.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}