@leeguoo/wrangler-accounts 1.2.2 → 1.3.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;

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.3.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
 
@@ -238,6 +251,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.