@leeguoo/wrangler-accounts 1.2.2 → 1.4.0

package/bin/wrangler-accounts.js

@@ -442,16 +442,13 @@ function main() {
       const session = readSessionState(cfgPath);
       const meta = readMeta(profileDir);
       const identity = getMetaIdentity(meta);
-      let status;
-      if (session.expired === true) status = "expired";
-      else if (session.expired === false) status = "valid";
-      else status = "unknown";
       return {
         name,
         isDefault: name === defaultName,
         isActive: name === activeName,
-        status,
+        status: session.effective, // 'valid' | 'refreshable' | 'expired' | 'unknown'
         expirationTime: session.expirationTime,
+        hasRefreshToken: session.hasRefreshToken,
         identity,
         verified: null,
         verifyError: null,
@@ -528,6 +525,7 @@ function main() {
       name: e.name,
       status:
         e.status === "expired" ? "EXPIRED"
+        : e.status === "refreshable" ? "valid*"
         : e.status === "valid" ? "valid"
         : "unknown",
       expires: formatExpiry(e.expirationTime),
@@ -563,17 +561,23 @@ function main() {
     console.log();
     if (opts.deep) {
       console.log(
-        "Legend: * = default profile, VERIFIED ✓ = wrangler whoami succeeded in shadow HOME, ✗ = authoritative failure",
+        "Legend: * = default profile | STATUS valid = access token fresh | valid* = access token expired but refresh_token will auto-refresh",
+      );
+      console.log(
+        "        EXPIRED = access token expired and no refresh_token, must 'login <name>' again",
+      );
+      console.log(
+        "        VERIFIED ✓ = 'wrangler whoami' succeeded in shadow HOME (authoritative) | ✗ = failed",
       );
     } else {
       console.log(
-        "Legend: * = default profile, EXPIRED = access token past expiration_time (wrangler may still auto-refresh)",
+        "Legend: * = default profile | STATUS valid = access token fresh | valid* = access token expired but refresh_token will auto-refresh",
       );
       console.log(
-        "        STATUS is derived from the saved file only. For a live check that runs 'wrangler whoami' against Cloudflare,",
+        "        EXPIRED = access token expired and no refresh_token, must 'login <name>' again | unknown = no expiration_time saved",
       );
       console.log(
-        "        pass --deep (slower, makes network calls).",
+        "        STATUS is file-only. For a live check against Cloudflare, pass --deep (slower, makes network calls).",
       );
     }
     return;
@@ -691,6 +695,64 @@ function main() {
     if (!isValidName(name)) die(`Invalid profile name: ${name}`);
     ensureDir(profilesDir);
 
+    // Guard 1: refuse to run in a non-interactive context (CI, sub-agent,
+    // pipe). 'wrangler login' opens a browser and requires the user to
+    // click an authorize button. In a non-TTY context this hangs forever
+    // and any attempt is almost certainly an AI/script applying 'login'
+    // as if it were idempotent — it isn't.
+    if (!process.stdin.isTTY && !opts.force) {
+      die(
+        [
+          `'login' requires an interactive terminal — wrangler will open a browser`,
+          `and wait for authorization. Stdin is not a TTY here.`,
+          ``,
+          `If you are an AI agent or script trying to verify a profile is`,
+          `working, do NOT use 'login'. Use one of these instead:`,
+          ``,
+          `  wrangler-accounts whoami --profile ${name}    # static check (meta.json)`,
+          `  wrangler-accounts list --deep                 # live check (network call)`,
+          ``,
+          `If you really need to re-authenticate this profile non-interactively,`,
+          `pass --force to bypass this guard (the OAuth flow will still need a`,
+          `browser to complete).`,
+        ].join("\n"),
+        1,
+      );
+    }
+
+    // Guard 2: refuse to overwrite an existing profile that's already
+    // healthy unless --force is passed. 'login' is destructive — it
+    // OVERWRITES the saved profile by design. If the profile is already
+    // valid, the caller almost certainly meant to verify, not re-create.
+    const existingCfg = path.join(profilesDir, name, "config.toml");
+    if (fs.existsSync(existingCfg) && !opts.force) {
+      const session = readSessionState(existingCfg);
+      const looksHealthy = session.effective === "valid" || session.effective === "refreshable";
+      if (looksHealthy) {
+        die(
+          [
+            `Profile '${name}' already exists and looks healthy:`,
+            `  status:           ${session.effective}`,
+            `  expirationTime:   ${session.expirationTime || "(none)"}`,
+            `  hasRefreshToken:  ${session.hasRefreshToken}`,
+            ``,
+            `'login' is DESTRUCTIVE — it opens a browser and overwrites the saved`,
+            `profile. If you only wanted to verify the profile works, run instead:`,
+            ``,
+            `  wrangler-accounts whoami --profile ${name}     # fast, no network`,
+            `  wrangler-accounts list --deep                  # authoritative, hits Cloudflare API`,
+            ``,
+            `If you really intend to re-authenticate (e.g. you revoked the token`,
+            `in the Cloudflare dashboard, or want to switch which OAuth account`,
+            `this profile is bound to), pass --force:`,
+            ``,
+            `  wrangler-accounts login ${name} --force`,
+          ].join("\n"),
+          1,
+        );
+      }
+    }
+
     // Create a shadow HOME without pre-linking .wrangler/config/default.toml.
     // wrangler login will write a fresh file into shadow/.wrangler/config/
     // which we then move into the profile directory.

package/lib/profile-store.js

@@ -39,20 +39,72 @@ function readExpirationTime(filePath) {
   return match ? match[1] : null;
 }
 
+function hasRefreshToken(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const text = fs.readFileSync(filePath, 'utf8');
+  // Any non-empty string value counts. Cloudflare's offline_access scope
+  // causes wrangler to store a refresh_token; profiles without that scope
+  // won't have one, and those are "really expired" once the access token
+  // runs out (~1h).
+  return /^\s*refresh_token\s*=\s*"[^"]+"/m.test(text);
+}
+
+/**
+ * Read the session state of a profile config.toml.
+ *
+ * Returns:
+ *   expirationTime:    ISO string of access_token expiry, or null
+ *   expired:           boolean — access_token past expirationTime, or null
+ *   hasRefreshToken:   boolean — whether the profile has a refresh_token
+ *                      that wrangler will auto-use for silent refresh
+ *   effective:         'valid' | 'refreshable' | 'expired' | 'unknown'
+ *     - 'valid':       access_token currently valid
+ *     - 'refreshable': access_token past expiry but refresh_token present,
+ *                      so wrangler will auto-refresh on next use (no user
+ *                      action needed)
+ *     - 'expired':     access_token past expiry AND no refresh_token,
+ *                      profile is genuinely broken, user must re-login
+ *     - 'unknown':     no expiration_time field, can't tell statically
+ */
 function readSessionState(filePath) {
   const expirationTime = readExpirationTime(filePath);
+  const refreshable = hasRefreshToken(filePath);
+
   if (!expirationTime) {
-    return { expirationTime: null, expired: null };
+    return {
+      expirationTime: null,
+      expired: null,
+      hasRefreshToken: refreshable,
+      effective: 'unknown',
+    };
   }
 
   const expiresAt = new Date(expirationTime);
   if (Number.isNaN(expiresAt.getTime())) {
-    return { expirationTime, expired: null };
+    return {
+      expirationTime,
+      expired: null,
+      hasRefreshToken: refreshable,
+      effective: 'unknown',
+    };
+  }
+
+  const expired = expiresAt.getTime() <= Date.now();
+
+  let effective;
+  if (!expired) {
+    effective = 'valid';
+  } else if (refreshable) {
+    effective = 'refreshable';
+  } else {
+    effective = 'expired';
   }
 
   return {
     expirationTime,
-    expired: expiresAt.getTime() <= Date.now(),
+    expired,
+    hasRefreshToken: refreshable,
+    effective,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeguoo/wrangler-accounts",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Cloudflare Wrangler multi-account manager — save, switch, and run wrangler against multiple Cloudflare Workers accounts with AWS-style --profile and per-invocation shadow HOME isolation.",
   "license": "MIT",
   "bin": {

package/skills/wrangler-accounts/SKILL.md

@@ -77,13 +77,26 @@ Use `--json` for structured output.
 ### List and inspect profiles
 
 - `wrangler-accounts list` — text table with NAME / STATUS / EXPIRES / IDENTITY columns
-- `wrangler-accounts list --json` — structured: array of `{name, isDefault, isActive, status, expirationTime, identity}`
+- `wrangler-accounts list --json` — structured: array of `{name, isDefault, isActive, status, expirationTime, hasRefreshToken, identity, verified, verifyError}`
 - `wrangler-accounts list --plain` — one profile name per line (scriptable)
 - `wrangler-accounts list --deep` — **authoritative** check: spawns `wrangler whoami` in a shadow HOME for every profile and reports whether Cloudflare actually accepts the credentials. Slower (makes network calls), but the only way to catch revoked refresh tokens or broken profile files.
 - `wrangler-accounts status` / `status --json`
 - Pass `--include-backups` to show hidden backup profiles.
 
-**Accuracy note:** the `STATUS` column without `--deep` is derived purely from the saved `expiration_time` and tells you *when the access token will expire*, not whether the profile is actually usable. Wrangler auto-refreshes access tokens via the refresh token, so an `EXPIRED` access token is often fine in practice. When the user needs a real verdict, suggest `wrangler-accounts list --deep`.
+**STATUS values (1.3.0+):**
+
+| value | meaning | user action |
+|---|---|---|
+| `valid` | access_token is currently valid | none |
+| `valid*` / `refreshable` | access_token past expiry **BUT** refresh_token present; wrangler will auto-refresh on next use | **none** — this is fine, don't scare the user |
+| `EXPIRED` / `expired` | access_token expired **AND** no refresh_token saved; profile is genuinely broken | `wrangler-accounts login <name>` |
+| `unknown` | profile file has no `expiration_time` field | run `list --deep` to verify live |
+
+**Cloudflare OAuth lifecycle reference:** access tokens are short-lived (~1 hour) by design. Every profile with `offline_access` in its scopes also has a long-lived refresh_token (~30 days, silently extended on use). Wrangler refreshes access tokens automatically whenever it runs a command and the current one is past expiry. **Do not tell the user to re-login just because `list` shows an expired access token** — check `hasRefreshToken` first. If the profile's STATUS is `valid*` / `refreshable`, nothing is wrong.
+
+The only time a user actually needs `wrangler-accounts login <name>` again is:
+1. STATUS is `EXPIRED` (no refresh_token at all — profile was saved without `offline_access` scope)
+2. OR `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (refresh token itself got invalidated)
 
 ### Save, sync, login, remove
 
@@ -147,6 +160,34 @@ wrangler-accounts list                 # confirm the profile is saved
 
 The login flow runs inside an isolated shadow `HOME`, so the user's real `~/.wrangler/config/default.toml` is never touched.
 
+> ⚠️ **`login` is destructive.** It opens a browser, requires the user to click "Authorize" interactively, and **OVERWRITES** the named profile. As of 1.4.0, `wrangler-accounts login <name>` refuses to run if (a) stdin is not a TTY, or (b) the profile already exists and looks healthy — both unless you pass `--force`. **Never run `login` to "verify" or "refresh" a profile** — see the antipattern below.
+
+### ❌ Antipattern: running `login` to verify a profile works
+
+This is wrong:
+```bash
+wrangler-accounts login Xdreamstar2025   # ❌ DON'T do this just to check
+```
+
+Reasons:
+1. `login` is **destructive** — it overwrites the saved profile with a brand new OAuth flow.
+2. `login` requires a **browser and an interactive terminal** — it cannot complete in a Bash sub-shell, CI runner, or sub-agent context. The command will hang waiting for the user.
+3. The Cloudflare access token in a healthy profile auto-refreshes via `refresh_token` — there is **nothing to "log in to"** when the profile already works.
+
+Use one of these instead:
+
+```bash
+wrangler-accounts whoami --profile Xdreamstar2025   # fast, reads meta.json, no network
+wrangler-accounts list --deep                       # authoritative, runs wrangler whoami per profile
+wrangler-accounts list                              # quick STATUS overview (valid / valid* / EXPIRED / unknown)
+```
+
+Only fall back to `wrangler-accounts login <name>` when:
+- The profile **does not exist yet** (creating a new account profile from scratch)
+- The profile shows `EXPIRED` (truly expired, no refresh_token left) — see STATUS table above
+- `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (server-side revocation)
+- The user **explicitly says** "re-authenticate this profile" / "log me in again"
+
 ### User wants: check which account a profile is tied to, without running wrangler
 
 ```bash
@@ -238,6 +279,56 @@ Or users can add a shell alias: `alias realhome='cd "$WRANGLER_ACCOUNT_REAL_HOME
 - "I want this account to stick for a while" → `wrangler-accounts default <name>`
 - "Just this one command" → `wrangler-accounts --profile <name> <wrangler-args>`
 
+### `[ERROR] A request to the Cloudflare API ... Authentication error [code: 10000]` with `code: 7403` ("not authorized to access this service")
+
+The OAuth token is fine but **the URL contains the wrong account ID**. wrangler caches the user's selected account in `wrangler-account.json`. If that cache file is shared across profiles, profile A's OAuth token gets paired with profile B's cached account ID, sending API calls to the wrong account. Symptoms:
+
+- `deploy` and `secret put` succeed (they don't put account ID in the URL path)
+- `d1 execute --remote`, `r2 object get/put`, anything else with `/accounts/<id>/...` in the URL fails with 7403
+
+**Fix path** (in order):
+
+1. **Are you on wrangler-accounts ≥ 1.2.2?** Run `wrangler-accounts --version`. If `< 1.2.2`, upgrade — earlier versions pointed `WRANGLER_CACHE_DIR` at a shared global path. 1.2.2 isolates the cache per profile.
+2. **Clear the polluted shared cache** (one-time, even after upgrading):
+   ```bash
+   rm -f ~/.wrangler/cache/wrangler-account.json
+   rm -f ~/Library/Preferences/.wrangler/cache/wrangler-account.json   # macOS env-paths fallback
+   ```
+3. **Verify with `wrangler-accounts list --deep`** — the VERIFIED column for each profile should be `✓ ok`. If `✗`, the underlying OAuth session itself is broken; run `wrangler-accounts login <name>`.
+4. **Defense in depth**: set `CLOUDFLARE_ACCOUNT_ID=<correct-id>` in the calling environment. wrangler reads this env var directly and bypasses the cache entirely. Useful for scripts or one-off recovery commands:
+   ```bash
+   CLOUDFLARE_ACCOUNT_ID=<id> wrangler-accounts <profile> r2 object put ...
+   ```
+
+**What to tell the user**: "wrangler returned 7403 because it cached the wrong account ID alongside your OAuth token. This was a real bug in wrangler-accounts ≤ 1.2.1 (shared cache directory across profiles). Upgrade to 1.2.2 and clear the polluted cache."
+
+### "The OAuth config seems right, but the wrong account is being used"
+
+Same root cause as the 7403 above. Default to the same fix path.
+
+### `wrangler dev` (or any `--local` command) shows stale data after switching profiles
+
+Project-local state at `<project>/.wrangler/state/` is **NOT** isolated per profile — wrangler's `getLocalPersistencePath` (cli.js:149025) hardcodes the path next to `wrangler.toml` and the only override is the `--persist-to` CLI flag (no env var hook). So if profile A's `wrangler dev` populated a local D1 emulation, then you switch to profile B and run `wrangler dev` in the same directory, B sees A's emulated rows.
+
+This only affects `--local` simulations. **`--remote` commands hit Cloudflare directly and are unaffected** — that's the common case for d1/r2 work in a multi-account setup.
+
+Two clean fixes:
+
+1. **Use git worktrees** (recommended for any serious multi-profile dev workflow):
+   ```bash
+   git worktree add ../my-project-work main
+   git worktree add ../my-project-personal main
+   cd ../my-project-work && wrangler-accounts exec work     # isolated .wrangler/state/
+   cd ../my-project-personal && wrangler-accounts exec personal
+   ```
+2. **Clear state manually before switching**:
+   ```bash
+   rm -rf .wrangler/state
+   wrangler-accounts --profile <new> dev
+   ```
+
+`wrangler-accounts` does not auto-isolate `.wrangler/state/` because the only mechanism would be argv injection of `--persist-to`, which has too many failure modes (different subcommands accept persistTo at different positions, can't override user-supplied flags, path selection is ambiguous between per-profile and per-profile-per-project). The honest tradeoff is documented in the "What is and isn't isolated" table above — partial isolation with hidden gotchas would be worse than honest sharing.
+
 ### Shell history / `.zsh_history` seems to grow when running `exec`
 
 Intentional. By design the shadow HOME symlinks all top-level entries of real HOME except `.wrangler`, so shell history writes pass through to the real file. This is a **convenience** bias, not a clean-room sandbox — the goal is that `exec` subshells feel like a normal terminal with a different Cloudflare account, not a jail.