aethel 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.1 (2026-04-05)
+
+- Improve setup SOP: default credentials to ~/.config/aethel/ with guided error message
+
 ## 0.3.0 (2026-04-05)
 
 - Refactor to Repository pattern; add TUI command system with catalog, CLI runner, and tests

package/README.md

@@ -33,14 +33,38 @@ npm run install:cli   # symlinks `aethel` into ~/.local/bin
 
 ## 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** (Desktop application)
-4. Download the credentials JSON and save it as `credentials.json` in your project root
+### 1. Get Google OAuth Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or select an existing one)
+3. Enable the **Google Drive API** (APIs & Services → Library)
+4. Go to **APIs & Services → Credentials**
+5. Click **Create Credentials → OAuth 2.0 Client ID**
+6. Application type: **Desktop application**
+7. Download the JSON file
+
+### 2. Save Credentials
+
+Save the downloaded JSON as `~/.config/aethel/credentials.json`:
+
+```bash
+mkdir -p ~/.config/aethel
+mv ~/Downloads/client_secret_*.json ~/.config/aethel/credentials.json
+```
+
+You can also place `credentials.json` in the current directory, or pass a custom path with `--credentials`.
+
+### 3. Authenticate
 
 ```bash
 aethel auth                    # opens browser, saves token.json
-aethel init --local-path ./workspace --drive-folder <folder-id>
+```
+
+### 4. Initialize a Workspace
+
+```bash
+aethel init --local-path ./my-drive     # sync entire My Drive
+aethel init --local-path ./workspace --drive-folder <folder-id>  # sync specific folder
 ```
 
 > `credentials.json` and `token.json` are local secrets — never commit them.
@@ -143,8 +167,8 @@ build/
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `credentials.json` | Path to OAuth credentials |
-| `GOOGLE_DRIVE_TOKEN_PATH` | `token.json` | Path to cached OAuth token |
+| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `~/.config/aethel/credentials.json` | Path to OAuth credentials |
+| `GOOGLE_DRIVE_TOKEN_PATH` | `~/.config/aethel/token.json` | Path to cached OAuth token |
 | `AETHEL_DRIVE_CONCURRENCY` | `40` | Max concurrent Drive API requests |
 
 ## Architecture

package/package.json

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

package/src/core/auth.js

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
 import fsSyncFallback from "node:fs";
 import http from "node:http";
+import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { URL } from "node:url";
 import { google } from "googleapis";
 import open from "open";
@@ -10,8 +10,7 @@ import open from "open";
 const SCOPES = ["https://www.googleapis.com/auth/drive"];
 const DEFAULT_CREDENTIALS_PATH = "credentials.json";
 const DEFAULT_TOKEN_PATH = "token.json";
-const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = path.resolve(MODULE_DIR, "..", "..");
+const CONFIG_DIR = path.join(os.homedir(), ".config", "aethel");
 const AUTH_TIMEOUT_MS = 120_000;
 
 // ── Path resolution ─────────────────────────────────────────────────
@@ -22,7 +21,12 @@ function resolvePath(candidatePath, fallbackFileName) {
       ? candidatePath
       : path.resolve(process.cwd(), candidatePath);
   }
-  return path.join(PROJECT_ROOT, fallbackFileName);
+  // Also check cwd before falling back to ~/.config/aethel/
+  const cwdPath = path.resolve(process.cwd(), fallbackFileName);
+  if (fsSyncFallback.existsSync(cwdPath)) {
+    return cwdPath;
+  }
+  return path.join(CONFIG_DIR, fallbackFileName);
 }
 
 export function resolveCredentialsPath(customPath) {
@@ -47,7 +51,15 @@ async function loadClientConfig(credentialsPath) {
     raw = await fs.readFile(credentialsPath, "utf8");
   } catch {
     throw new Error(
-      `OAuth credentials file was not found. Expected path: ${credentialsPath}`
+      `OAuth credentials file not found: ${credentialsPath}\n\n` +
+      "Setup steps:\n" +
+      "  1. Go to https://console.cloud.google.com/\n" +
+      "  2. Create a project and enable the Google Drive API\n" +
+      "  3. Create an OAuth 2.0 Client ID (Desktop application)\n" +
+      "  4. Download the credentials JSON and save it as:\n" +
+      `     ${path.join(CONFIG_DIR, DEFAULT_CREDENTIALS_PATH)}\n\n` +
+      "Or pass a custom path:\n" +
+      "  aethel auth --credentials /path/to/credentials.json"
     );
   }