@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/dr-switch-user/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: dr-switch-user
+description: Set an in-conversation default --account for dr-cli (Datarails CLI), and impersonate a customer via `dr login-as` when needed. Use when the user wants to switch identity, log in as someone else, impersonate a customer, or list saved identities. Triggers - "switch to <email>", "switch user to <email>", "use <email>", "use <email> from now on", "login as <email>", "log me in as <email>", "impersonate <email>", "show me available identities", "show stored identities", "list saved users", "who am I logged in as", "which dr accounts are saved", "/switch-user", "/switch-user <email>". The session default itself is not written to any file - it's a rule Claude follows for the rest of this conversation; credential storage is handled by dr login / dr login-as. Install, update, or log in to the CLI → /dr-cli:install; a CLI that is installed but misbehaving → /dr-cli:doctor.
+---
+
+# dr-switch-user — set the session default --account for dr-cli
+
+## Why this skill exists
+
+`dr-cli` is **stateless with respect to identity** — every command takes
+`--account <email>` separately. There is no "active user" in the CLI. So
+"switching user" really means: tell Claude which email to pass as
+`--account` for the rest of *this conversation only*.
+
+This skill does three things:
+
+1. **Verify** the chosen email has working credentials on at least one
+   server, by probing each server's local JWT via `dr whoami`.
+2. **Add the identity** if credentials are missing — either by
+   impersonating a customer with `dr login-as <email>` (JWT only, no
+   browser; needs an operator login first), or by a browser `dr login`
+   for the operator's own identity. See Section 3.
+3. **Record an in-conversation session default** — a directive Claude
+   obeys for the rest of this chat.
+
+> **Impersonation is now a real CLI command.** `dr login-as <email>
+> --server <X>` mints an impersonation JWT from an existing operator login
+> and stores it as a switchable `(server, email)` identity — no browser
+> round-trip. This is the correct path for "log me in as <customer>";
+> browser `dr login` can only sign you in as whoever the browser is.
+
+## Hard rules
+
+- **Never persist.** Do not write to `MEMORY.md`, `CLAUDE.md`,
+  `settings.json`, or any other file. The default lives only in
+  Claude's context for this conversation. Opening a new Claude Code
+  session = no default carries over.
+- **Never assume which identity to use.** This skill is the cure for
+  exactly that mistake. If the user's intent is ambiguous (no email
+  given, multiple matches, mismatch after login), **ask**.
+- **Server is always passed per-command.** The default scopes only
+  `--account`. `--server` stays explicit on every dr invocation.
+
+## Inputs
+
+The skill is invoked in one of these forms:
+
+| Form                                       | Meaning                                              |
+| ------------------------------------------ | ---------------------------------------------------- |
+| `/switch-user <email>` or "switch to <email>" | Set default to `<email>` (Sections 2 + 3 below)   |
+| `/switch-user` (no arg) or "show identities" | List all stored identities + offer picker (Section 4) |
+| "stop defaulting" / "clear default user"   | Remove any active session default                    |
+
+## Server keys (the universe to probe)
+
+`US`, `US2`, `UK`, `CA`, `EU`, `DEV`, `DEV-1`, `TEST`, `TEST-1`, `TEST-2`, `TEST-3`, `TEST-4`, `TEST-5`, `TEST-6`, `TEST-7`, `DEMO` — case-insensitive.
+These are the only valid `--server` values dr-cli accepts.
+
+---
+
+## Section 1 — Validate the email
+
+Before probing, sanity-check the input:
+
+- Must contain a single `@`.
+- Must have at least one character before and after `@`.
+- Must contain at least one `.` after the `@`.
+
+If invalid: print `<input> doesn't look like an email — usage:
+/switch-user <user>@<domain>` and stop. Do not probe.
+
+---
+
+## Section 2 — Probe one server for the email (happy path)
+
+**Do NOT probe all 16 servers.** When the user invokes the skill with an
+email, they have a specific server in mind. Asking is cheap; guessing
+across all servers wastes turns and can scope the default wrongly.
+
+### 2.1. Ask which server
+
+Print verbatim, then wait for the user's reply. Do not guess from
+context, prior turns, or `userEmail`:
+
+> Which server should I switch to `<email>` on? (`US`, `US2`, `UK`, `CA`, `EU`, `DEV`, `DEV-1`, `TEST`, `TEST-1`, `TEST-2`, `TEST-3`, `TEST-4`, `TEST-5`, `TEST-6`, `TEST-7`, `DEMO`)
+
+### 2.2. Probe that one server
+
+Run a single Bash call:
+
+```bash
+dr whoami --server <X> --account <email> 2>&1 || true
+```
+
+`whoami` is purely offline (decodes the locally-stored JWT, no network).
+Classify the output:
+
+| Result                                                 | Meaning                                  |
+| ------------------------------------------------------ | ---------------------------------------- |
+| Exit 0, prints matching email + JWT exp                | Stored on this server → Section 5 (if it shows `Impersonated by:`, it's a login-as identity — still stored, still fine) |
+| `not logged in to <SERVER>`                            | Not stored → Section 3 (add it — login-as or browser login) |
+| `no JWT stored for <server>`                           | Creds malformed → Section 3 (add it — login-as or browser login) |
+| `multiple accounts stored for <SERVER>: ...` with the requested email in the list | Stored on this server (defensive case — passing --account should normally avoid this) → Section 5 |
+| Anything else                                          | Surface verbatim, do not record a default |
+
+---
+
+## Section 3 — Add the identity (email not stored on the chosen server)
+
+The server was already chosen in Section 2.1. There are **two ways** to add
+`<email>`, and which is correct depends on *whose* identity it is:
+
+- **3A — Impersonate a customer with `dr login-as` (JWT, no browser).**
+  Use when `<email>` is a **customer / another user** you want to act as,
+  and you (an operator/support user) are already logged in on this server.
+  This is the normal path for "log me in as <customer>".
+- **3B — Browser `dr login` (your own / the operator identity).**
+  Use when `<email>` is **you** (the operator) and you just haven't logged
+  in on this server yet — or when there's *no* operator login on the server
+  at all, so nobody can authorize an impersonation.
+
+Decide with one offline probe (no network) — list what's stored on <X>:
+
+```bash
+dr whoami --server <X> 2>&1 || true
+```
+
+- **An operator (non-impersonated) login already exists on <X>** and
+  `<email>` is *not* that operator → **3A** (login-as).
+- **Nothing is stored on <X>**, or the only way to reach `<email>` is to
+  sign in as yourself → **3B** (browser login).
+
+If it's genuinely ambiguous whether `<email>` is a customer to impersonate
+or an operator to sign in as, **ask** — don't guess.
+
+### 3A. Impersonate via `dr login-as`
+
+```
+dr login-as <email> --server <X>
+```
+
+Resolves `<email>` to a user id via `can_login_as`, mints an impersonation
+JWT from the monolith authorized by the operator, and stores it as a
+switchable `(server, email)` identity — no browser, no TTY prompt.
+
+- **Multiple operators stored on <X>** → the CLI refuses and lists them.
+  Re-run with `--as <operator-email>` to pick who authorizes the mint.
+- **Email doesn't resolve** → the CLI suggests near matches; if you already
+  know the id, re-run with `--user-id <n>`.
+- **No operator login on <X>** → the CLI says to run `dr login` first. Fall
+  back to **3B** to establish the operator, then re-run login-as.
+- **Denials** surface as clear messages — *not permitted to impersonate*,
+  *inactive*, *impersonation service unavailable*. Surface verbatim; do not
+  retry; do not record a default.
+- **`login-as` needs dr ≥ 1.3.24.** Older installs answer `unknown command
+  'login-as'`. If the browser Login-As works but the CLI "can't", check
+  `dr --version` / `dr update` first — that's the common cause, not permissions.
+- **The product `SUPER_ADMIN` role ≠ Django `is_superuser`.** `login-as` runs
+  the *same* gate as the browser Login-As (`it_loginas`) and only blocks
+  genuine Django `is_superuser` / sync-service / application targets — a
+  customer whose product role is `SUPER_ADMIN` is still impersonable (verified
+  on DEMO). There is **no** equal-or-higher-privilege rule, so a `can-login-as`
+  hit is generally reliable. `not permitted` means a true superuser/sync/
+  application target, or you the operator lack scope (superuser operator → any
+  non-superuser; supporting-manager → only users in your supported orgs). If it
+  fires, surface the message — don't fall back to browser login as that email.
+- **Success** prints
+  `Logged into <X> as <email> (impersonated by <operator>). JWT expires in …`
+  → go to Section 5 (record the default, scoped to this server). No
+  post-login identity check needed — login-as targets `<email>` directly,
+  so there's no browser-mismatch risk.
+
+### 3B. Browser login via `dr login`
+
+Do **not** prompt the user before running login. Just run it. The
+post-login identity check (3B.2) is the safety net for the
+browser-signed-in-as-the-wrong-account case — we catch the mismatch after
+and let the user decide.
+
+Optionally print a single short status line like *"Running `dr login
+--server <X>` — if your browser is signed in as a different account, the
+OAuth flow will pick that one and I'll flag the mismatch after. To
+impersonate a customer instead, I can use `dr login-as` once there's an
+operator login here."* **Do not wait for a reply.**
+
+```
+dr login --server <X>
+```
+
+(No `--account` flag — `dr login` doesn't accept one; the browser flow
+determines identity.)
+
+#### 3B.2. Verify post-login identity
+
+Capture the email from the success line:
+
+```
+Logged into <X> as <whoever>@datarails.com. JWT expires in ...
+```
+
+Compare `<whoever>@datarails.com` to the requested `<email>`:
+
+- **Match** → loop back to Section 5 (announce + record default,
+  scoped to this server).
+- **Mismatch** → print and stop:
+
+  > Browser logged you in as `<whoever>@datarails.com`, not `<email>`. Three options: (1) if `<email>` is a customer, keep `<whoever>` as the operator and re-run `/switch-user <email>` — I'll impersonate via `dr login-as`; (2) sign out of the browser and re-run `/switch-user <email>`; or (3) accept `<whoever>` as the new session default instead. Which?
+
+  Do **not** auto-pick. Do **not** silently accept the wrong identity.
+
+#### 3B.3. Login failures
+
+Browser closed, timeout, network error: surface dr-cli's stderr
+verbatim. Do not retry. Do not record any default.
+
+---
+
+## Section 4 — No-arg flow: list saved identities + picker
+
+User invokes `/switch-user` with no email, or asks "show identities" /
+"who's logged in" / "which accounts are saved".
+
+### 4.1. Probe every server (no --account)
+
+Use the **single-loop pattern** (same reason as Section 2 — parallel
+tool calls cancel each other on the first non-zero exit):
+
+```bash
+for srv in US US2 UK CA EU DEV DEV-1 TEST TEST-1 TEST-2 TEST-3 TEST-4 TEST-5 TEST-6 TEST-7 DEMO; do
+  echo "=== $srv ==="
+  dr whoami --server "$srv" 2>&1 || true
+done
+```
+
+Possible outcomes per server (parse each `=== <srv> ===` block):
+
+- **Exit 0** → one identity is stored; capture the email from output.
+- **Exit 1 with `multiple accounts stored for <SERVER>:`** → parse
+  the email list from stderr. Each row shape: `  - <email> (last used <date>)`.
+- **`not logged in`** or **`no JWT stored`** → skip this server.
+
+### 4.2. Render a picker
+
+Print a numbered, flat list of every `(server, email, last-used)` pair
+found:
+
+```
+Stored identities:
+  1. US     alice@datarails.com    (last used 2026-05-14)
+  2. US     bob@datarails.com      (last used 2026-05-15)
+  3. DEV    alice@datarails.com    (last used 2026-05-10)
+  4. DEMO   carol@datarails.com    (last used 2026-04-02)
+
+Reply with a number to set as session default, or an email to set that
+email across every server it appears on. Reply 'login' to add a new
+identity (browser login for yourself, or `dr login-as` to impersonate a
+customer).
+```
+
+Wait for the user's pick.
+
+### 4.3. Resolve the pick
+
+- **Number** → default is scoped to that one specific `(server, email)`
+  pair. Jump straight to Section 5.
+- **Email** → ambiguous when the email shows up on multiple rows. Ask:
+  *"On which server should I switch to `<email>`? (servers shown above
+  where it's stored: <list>)"* — then jump to Section 5 with the
+  chosen `(email, server)`. Do not guess.
+- **`login`** → ask which server to log in to (Section 2.1 prompt),
+  then enter Section 3.
+
+### 4.4. Empty case
+
+If no identities are stored anywhere across all 16 servers → skip the
+picker entirely, print "No identities are currently stored." and ask
+the user if they want to log in (then enter Section 3).
+
+---
+
+## Section 5 — Announce + record the session default
+
+After Section 2 or 3 or 4 successfully resolves an `(email, server)`
+pair, print **two things** to the user.
+
+### 5.1. Human-readable announcement
+
+> `<email>` is logged in on **<server>**. For the rest of this session I'll pass `--account <email>` on dr commands targeting that server. For any other server I'll ask before running.
+
+If the identity is an impersonation (it was created by `dr login-as`, or
+`whoami` shows `Impersonated by: <operator>`), add:
+
+> This is an impersonated identity (operator: `<operator>`). Its token refreshes silently and auto-remints from the operator, so you won't be re-prompted until the operator's own login expires.
+
+### 5.2. Directive block (delimited, durable across compaction)
+
+This is the actual mechanism. Print exactly this shape — fenced as
+code, with the visible separators — so Claude treats it as a binding
+rule, not chat prose:
+
+```
+======== dr-cli session default (this conversation only) ========
+Default --account: <email>
+Scoped to server:  <X>
+
+Rule for every subsequent dr-cli invocation in this session:
+  - If --server is <X>: pass --account <email> automatically.
+    Do not ask the user.
+  - If --server is any other key: ASK the user which account before
+    running. Do not guess.
+  - If the user later says "switch to <other email>", "use <other>",
+    "stop defaulting", "clear default user", or invokes /switch-user
+    again: that supersedes this rule.
+
+Do not persist this to memory, MEMORY.md, CLAUDE.md, settings.json,
+or any file. It dies with this conversation.
+=================================================================
+```
+
+After printing the directive, **honor it for the rest of the
+conversation**: on every `dr <subcommand>` invocation thereafter, if
+`--server` matches the scoped server, automatically include
+`--account <email>`. If `--server` is any other key, pause and ask
+before running.
+
+---
+
+## Section 6 — Clearing the default
+
+If the user says "stop defaulting", "clear default user", "no default",
+or `/switch-user --clear`:
+
+1. Print: `Cleared. From now on I'll ask which account to use on each dr command.`
+2. Mentally retire the directive block from Section 5. On subsequent
+   `dr` calls, ask the user for `--account` before running, exactly as
+   if the skill had never been invoked.
+
+Do **not** rewrite or delete files. Do **not** run any dr commands.
+
+---
+
+## Section 7 — Override semantics
+
+If the user re-invokes `/switch-user <other email>` while a default is
+already active:
+
+- Run Sections 1–5 against the new email from scratch.
+- The new directive block fully replaces the old one. No merging, no
+  per-server overrides.
+
+If the user reinvokes `/switch-user` (no arg):
+
+- Run Section 4 from scratch.
+- The picker shows the current state of the keychain, including any
+  identity that was just added by an earlier `/switch-user` call.
+
+---
+
+## Edge cases
+
+| Case                                                                  | Behavior                                                                                                                                                |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Email has a typo / wrong format                                       | Reject up-front (Section 1). Do not probe.                                                                                                              |
+| `dr` binary not on PATH                                               | First probe fails with `command not found`. Surface verbatim plus hint: `Run node scripts/install.mjs from the dr-cli repo to install the dr binary.`   |
+| JWT expired but refresh token alive                                   | `whoami` decodes locally and still prints the email — treat as stored. dr-cli auto-refreshes on the next real network call.                             |
+| Refresh token dead                                                    | Not visible at switch-time (whoami is offline). User will hit `session expired` on their next real `dr` command — at that point they should re-invoke `/switch-user <email>` to re-login. |
+| Impersonated identity, its refresh dies                               | dr-cli auto-remints a fresh impersonation JWT from the operator on the next real command — no re-invoke needed, unless the **operator's own** login has also expired (then re-login the operator, then re-run `dr login-as`). |
+| Target email you can't impersonate (`not permitted` / `inactive`)     | `dr login-as` fails with that message. Surface verbatim. Do not fall back to browser login as that email. Do not record a default. |
+| User cancels mid-login (closes browser, Ctrl-C, timeout)              | dr exits non-zero with a cancel/timeout message. Surface verbatim. Do not record any default. Do not retry automatically.                              |
+| Same email logged in on multiple servers, user picks the email (not a numbered row from the picker) | Ask the user which of the matching servers to scope to. Do not guess.                                                                                    |
+| Login succeeds, post-login email matches requested email              | Section 5 with the just-logged-in server in scope.                                                                                                      |
+| Login succeeds, post-login email does NOT match                       | Section 3B.2 mismatch prompt. Do not record any default until the user decides.                                                                          |
+
+---
+
+## What this skill does NOT do
+
+- It does **not** write the session default to any file. But it *does*
+  trigger `dr login` / `dr login-as` when an identity is missing, and those
+  commands write credentials to the keychain (the skill never touches the
+  keychain directly). Refresh and impersonation auto-remint are handled by
+  dr-cli itself.
+- It does **not** write to `MEMORY.md`, `CLAUDE.md`,
+  `settings.json`, or anywhere else on disk. The default is purely
+  conversational.
+- It does **not** survive context compaction guaranteed. If a long
+  conversation compresses the directive block away, the default
+  silently dies — re-invoke if you notice Claude stopped honoring it.
+- It does **not** validate refresh-token health (would require network
+  round-trips). If the refresh token is dead, the user will discover
+  it on their next real `dr` command, not at switch-time.
+- It does **not** override the dr-cli skill's own Guard Rail #5
+  ("never assume which identity to send as --account") for ambiguous
+  cases — that rule still applies. This skill is the *resolution
+  mechanism* for that ambiguity, not a way around it.