@bjesuiter/codex-switcher 1.7.4 → 1.8.1

package/README.md

@@ -6,12 +6,12 @@ Switch the coding-agents [pi](https://pi.dev/), [codex](https://developers.opena
 
 ## Latest Changes
 
-### 1.7.4
+### 1.8.1
 
 #### Fixes
 
-- Detect Cloudflare/bot-protection HTML challenge responses during OAuth device flow startup and token polling, and report an explicit `cloudflare_challenge` reason instead of only a generic HTTP 403.
-- When that challenge is detected, show a clear workaround: retry without `--device-flow` to use browser/manual callback flow.
+- Added platform-native secure-store write/read/delete probes to `cdx doctor` on Linux, macOS, and Windows, so runtime secure-store failures are detected directly instead of only reporting adapter capability.
+- Linux secure-store error handling now treats Secret Service `no result found` responses as missing-entry cases and classifies generic `Couldn't access platform secure storage` failures as unavailable-store errors with actionable guidance.
 
 see full changelog here: https://github.com/bjesuiter/codex-switcher/blob/main/CHANGELOG.md
 
@@ -153,12 +153,12 @@ cdx migrate-secrets
 | Command | Description |
 |---------|-------------|
 | `cdx` | Interactive mode |
-| `cdx login` | Add a new OpenAI account via OAuth |
-| `cdx login --device-flow` | Add account using OAuth device flow (no local browser callback needed) |
+| `cdx login` | Add a new OpenAI account via OAuth (recommended default flow; supports manual URL copy/paste callback completion with optional clipboard copy assist) |
+| `cdx login --device-flow` | Add account using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges) |
 | `cdx relogin` | Re-authenticate an existing account via OAuth |
-| `cdx relogin --device-flow` | Re-authenticate interactively using OAuth device flow |
+| `cdx relogin --device-flow` | Re-authenticate interactively using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges) |
 | `cdx relogin <account>` | Re-authenticate a specific account by ID or label |
-| `cdx relogin <account> --device-flow` | Re-authenticate specific account using OAuth device flow |
+| `cdx relogin <account> --device-flow` | Re-authenticate specific account using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges) |
 | `cdx switch` | Switch account (interactive picker) |
 | `cdx switch --next` | Cycle to next account |
 | `cdx switch <id>` | Switch to specific account |
@@ -177,6 +177,8 @@ cdx migrate-secrets
 | `cdx --version` | Show version |
 | `cdx --secret-store legacy-keychain <command>` | Override configured backend for this run (macOS legacy keychain) |
 
+> Tip: On SSH/VPS, prefer `cdx login` (without `--device-flow`) and complete login via manual callback URL/code copy-paste. The manual flow can offer clipboard copy assist (including OSC52 on compatible terminals) to avoid selecting long URLs. In Mosh sessions, OSC52 clipboard updates may be unreliable; if needed, use the printed fallback copy command or manual copy. Device flow can be blocked by Cloudflare challenge pages.
+
 ### Shell completion
 
 Generate and source completion scripts:

package/cdx.mjs

@@ -6,7 +6,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { deletePassword, getPassword, listBackends, setPassword, useBackend } from "@bjesuiter/cross-keychain";
 import { createInterface } from "node:readline/promises";
 import { randomBytes } from "node:crypto";
@@ -15,7 +15,7 @@ import { generatePKCE } from "@openauthjs/openauth/pkce";
 import http from "node:http";
 
 //#region package.json
-var version = "1.7.4";
+var version = "1.8.1";
 
 //#endregion
 //#region lib/platform/path-resolver.ts
@@ -256,7 +256,7 @@ const getBrowserLauncher = (platform = process.platform, url) => {
 		label: "xdg-open"
 	};
 };
-const isCommandAvailable = (command, platform = process.platform) => {
+const isCommandAvailable$1 = (command, platform = process.platform) => {
 	const probe = platform === "win32" ? "where" : "which";
 	return Bun.spawnSync({
 		cmd: [probe, command],
@@ -269,13 +269,13 @@ const getBrowserLauncherCapability = (platform = process.platform) => {
 	return {
 		command: launcher.command,
 		label: launcher.label,
-		available: isCommandAvailable(launcher.command, platform)
+		available: isCommandAvailable$1(launcher.command, platform)
 	};
 };
 const openBrowserUrl = (url, options = {}) => {
 	const platform = options.platform ?? process.platform;
 	const spawnImpl = options.spawnImpl ?? spawn;
-	const commandAvailable = options.isCommandAvailableImpl ?? isCommandAvailable;
+	const commandAvailable = options.isCommandAvailableImpl ?? isCommandAvailable$1;
 	const launcher = getBrowserLauncher(platform, url);
 	if (!commandAvailable(launcher.command, platform)) return {
 		ok: false,
@@ -304,6 +304,192 @@ const openBrowserUrl = (url, options = {}) => {
 	}
 };
 
+//#endregion
+//#region lib/platform/clipboard.ts
+const isCommandAvailable = (command, platform = process.platform) => {
+	const probe = platform === "win32" ? "where" : "which";
+	return Bun.spawnSync({
+		cmd: [probe, command],
+		stdout: "pipe",
+		stderr: "pipe"
+	}).exitCode === 0;
+};
+const isLikelyMoshSession = (env = process.env) => Boolean(env.MOSH_IP || env.MOSH_KEY || env.MOSH_PREDICTION_DISPLAY);
+const isLikelyRemoteSession = (env = process.env) => {
+	if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) return true;
+	return isLikelyMoshSession(env);
+};
+const hasDisplayServer = (env) => Boolean(env.WAYLAND_DISPLAY || env.DISPLAY);
+const supportsOsc52 = (isTTY, env) => {
+	if (!isTTY) return false;
+	if ((env.TERM ?? "").toLowerCase() === "dumb") return false;
+	return true;
+};
+const getLocalClipboardTargets = (platform, env, commandExists) => {
+	if (platform === "darwin") return commandExists("pbcopy", platform) ? [{
+		kind: "command",
+		method: "pbcopy",
+		command: "pbcopy",
+		args: []
+	}] : [];
+	if (platform === "win32") {
+		const targets = [];
+		if (commandExists("clip", platform)) targets.push({
+			kind: "command",
+			method: "clip",
+			command: "cmd",
+			args: ["/c", "clip"]
+		});
+		if (commandExists("powershell", platform)) targets.push({
+			kind: "command",
+			method: "powershell",
+			command: "powershell",
+			args: [
+				"-NoProfile",
+				"-Command",
+				"$v=[Console]::In.ReadToEnd(); Set-Clipboard -Value $v"
+			]
+		});
+		if (commandExists("pwsh", platform)) targets.push({
+			kind: "command",
+			method: "powershell",
+			command: "pwsh",
+			args: [
+				"-NoProfile",
+				"-Command",
+				"$v=[Console]::In.ReadToEnd(); Set-Clipboard -Value $v"
+			]
+		});
+		return targets;
+	}
+	const targets = [];
+	const wayland = Boolean(env.WAYLAND_DISPLAY);
+	const x11 = Boolean(env.DISPLAY);
+	if (isLikelyRemoteSession(env) && !hasDisplayServer(env)) return targets;
+	if (wayland && commandExists("wl-copy", platform)) targets.push({
+		kind: "command",
+		method: "wl-copy",
+		command: "wl-copy",
+		args: []
+	});
+	if ((x11 || !wayland) && commandExists("xclip", platform)) targets.push({
+		kind: "command",
+		method: "xclip",
+		command: "xclip",
+		args: ["-selection", "clipboard"]
+	});
+	if ((x11 || !wayland) && commandExists("xsel", platform)) targets.push({
+		kind: "command",
+		method: "xsel",
+		command: "xsel",
+		args: ["--clipboard", "--input"]
+	});
+	if (!wayland && commandExists("wl-copy", platform)) targets.push({
+		kind: "command",
+		method: "wl-copy",
+		command: "wl-copy",
+		args: []
+	});
+	return targets;
+};
+const resolveClipboardTargets = (context = {}, commandExists = isCommandAvailable) => {
+	const platform = context.platform ?? process.platform;
+	const env = context.env ?? process.env;
+	const isTTY = context.isTTY ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY));
+	const localTargets = getLocalClipboardTargets(platform, env, commandExists);
+	const remote = isLikelyRemoteSession(env);
+	const allowOsc52 = supportsOsc52(isTTY, env);
+	const result = [];
+	if (remote && allowOsc52) result.push({
+		kind: "osc52",
+		method: "osc52"
+	});
+	result.push(...localTargets);
+	if (!remote && allowOsc52) result.push({
+		kind: "osc52",
+		method: "osc52"
+	});
+	return result;
+};
+const buildOsc52Sequence = (text, env = process.env) => {
+	const osc = `\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`;
+	if (env.TMUX) return `\u001bPtmux;\u001b${osc}\u001b\\`;
+	const term = (env.TERM ?? "").toLowerCase();
+	if (env.STY || term.startsWith("screen")) return `\u001bP${osc}\u001b\\`;
+	return osc;
+};
+const defaultRunCommand = (command, args, input) => {
+	const result = spawnSync(command, args, {
+		input,
+		encoding: "utf8",
+		windowsHide: true
+	});
+	if (result.status === 0) return { ok: true };
+	const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+	const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
+	return {
+		ok: false,
+		error: stderr || stdout || `exit status ${result.status ?? "unknown"}`
+	};
+};
+const tryCopyToClipboard = (text, options = {}) => {
+	const commandExists = options.commandExistsImpl ?? isCommandAvailable;
+	const runCommand = options.runCommandImpl ?? defaultRunCommand;
+	const writeStdout = options.writeStdoutImpl ?? ((chunk) => {
+		process.stdout.write(chunk);
+	});
+	const targets = resolveClipboardTargets(options, commandExists);
+	if (targets.length === 0) return {
+		ok: false,
+		method: "none",
+		error: "No clipboard method available in this environment"
+	};
+	const errors = [];
+	for (const target of targets) {
+		if (target.kind === "osc52") {
+			const env = options.env ?? process.env;
+			try {
+				writeStdout(buildOsc52Sequence(text, env));
+				if (isLikelyMoshSession(env)) return {
+					ok: true,
+					method: "osc52",
+					warning: "Mosh session detected: OSC52 clipboard updates may not work reliably. If clipboard did not update, copy the URL manually from above."
+				};
+				return {
+					ok: true,
+					method: "osc52"
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				errors.push(`osc52: ${message}`);
+				continue;
+			}
+		}
+		const commandResult = runCommand(target.command, target.args, text);
+		if (commandResult.ok) return {
+			ok: true,
+			method: target.method
+		};
+		errors.push(`${target.method}: ${commandResult.error ?? "unknown error"}`);
+	}
+	return {
+		ok: false,
+		method: "none",
+		error: errors.join("; ")
+	};
+};
+const escapePosixSingleQuoted = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+const buildClipboardHelperCommand = (text, context = {}, commandExists = isCommandAvailable) => {
+	const commandTarget = resolveClipboardTargets(context, commandExists).find((target) => target.kind === "command");
+	if (!commandTarget) return null;
+	if (commandTarget.method === "powershell") {
+		const escaped = text.replace(/'/g, "''");
+		return `${commandTarget.command} -NoProfile -Command "Set-Clipboard -Value '${escaped}'"`;
+	}
+	if (commandTarget.method === "clip") return `printf '%s' ${escapePosixSingleQuoted(text)} | cmd /c clip`;
+	return `printf '%s' ${escapePosixSingleQuoted(text)} | ${commandTarget.command} ${commandTarget.args.join(" ")}`.trim();
+};
+
 //#endregion
 //#region lib/keychain.ts
 const SERVICE_PREFIX$3 = "cdx-openai-";
@@ -473,8 +659,38 @@ const ensureFallbackConsent = async (scope, warningMessage) => {
 //#region lib/secrets/linux-cross-keychain.ts
 const SERVICE_PREFIX$2 = "cdx-openai-";
 const LINUX_FALLBACK_SCOPE = "linux:cross-keychain:secret-service";
+const MISSING_ENTRY_MARKERS = [
+	"no matching entry found in secure storage",
+	"password not found",
+	"no stored credentials found",
+	"credential not found",
+	"no result found"
+];
+const STORE_UNAVAILABLE_MARKERS = [
+	"unable to initialize linux secure-store backend",
+	"no keyring backend could be initialized",
+	"native keyring module not available",
+	"secret service operation failed",
+	"couldn't access platform secure storage",
+	"dbus",
+	"d-bus",
+	"org.freedesktop.secrets",
+	"service unavailable"
+];
 let backendInitPromise$2 = null;
 let selectedBackend$2 = null;
+const getErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const classifyLinuxSecureStoreError = (error) => {
+	const message = getErrorMessage(error).toLowerCase();
+	if (MISSING_ENTRY_MARKERS.some((marker) => message.includes(marker))) return "missing_entry";
+	if (STORE_UNAVAILABLE_MARKERS.some((marker) => message.includes(marker))) return "store_unavailable";
+	return "other";
+};
+const createLinuxSecureStoreUnavailableError = (details) => {
+	const guidance = "Linux secure store is unavailable. Ensure Secret Service is installed/running (for example gnome-keyring with secret-tool), then retry login.";
+	if (!details) return new Error(guidance);
+	return /* @__PURE__ */ new Error(`${guidance} Technical details: ${details}`);
+};
 const tryUseBackend$2 = async (backendId) => {
 	try {
 		await useBackend(backendId, getCrossKeychainBackendOverrides());
@@ -492,6 +708,20 @@ const selectBackend$2 = async () => {
 	if (await tryUseBackend$2("secret-service")) return "secret-service";
 	throw new Error("Unable to initialize Linux secure-store backend via cross-keychain.");
 };
+const setActiveBackend = (backendId) => {
+	selectedBackend$2 = backendId;
+	backendInitPromise$2 = Promise.resolve();
+};
+const trySwitchBackend = async (backendId, options = {}) => {
+	if (options.forWrite && backendId === "secret-service") await ensureFallbackConsent(LINUX_FALLBACK_SCOPE, "⚠ Security warning: only the cross-keychain Linux fallback backend is available.\nThis path relies on shell-based `secret-tool` operations for Secret Service access.\nCompared to native bindings, secrets may be more exposed to process inspection/logging while helper commands run.");
+	try {
+		await useBackend(backendId, getCrossKeychainBackendOverrides());
+		setActiveBackend(backendId);
+		return true;
+	} catch {
+		return false;
+	}
+};
 const ensureLinuxBackend = async (options = {}) => {
 	if (!backendInitPromise$2) backendInitPromise$2 = (async () => {
 		selectedBackend$2 = await selectBackend$2();
@@ -517,17 +747,75 @@ const parsePayload$2 = (accountId, raw) => {
 	return parsed;
 };
 const withService$1 = async (accountId, run, options = {}) => {
-	await ensureLinuxBackend(options);
-	return run(getLinuxCrossKeychainService(accountId));
+	try {
+		await ensureLinuxBackend(options);
+	} catch (error) {
+		throw createLinuxSecureStoreUnavailableError(getErrorMessage(error));
+	}
+	try {
+		return await run(getLinuxCrossKeychainService(accountId));
+	} catch (error) {
+		if (classifyLinuxSecureStoreError(error) === "store_unavailable") throw createLinuxSecureStoreUnavailableError(getErrorMessage(error));
+		throw error;
+	}
+};
+const trySaveWithSecretServiceFallback = async (accountId, serializedPayload) => {
+	if (!await trySwitchBackend("secret-service", { forWrite: true })) return {
+		ok: false,
+		error: /* @__PURE__ */ new Error("Unable to switch Linux secure-store backend to secret-service fallback.")
+	};
+	try {
+		await setPassword(getLinuxCrossKeychainService(accountId), accountId, serializedPayload);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+};
+const saveLinuxCrossKeychainPayload = async (accountId, payload) => {
+	const serialized = JSON.stringify(payload);
+	try {
+		await withService$1(accountId, (service) => setPassword(service, accountId, serialized), { forWrite: true });
+		return;
+	} catch (error) {
+		const kind = classifyLinuxSecureStoreError(error);
+		if (kind === "missing_entry" && selectedBackend$2 === "native-linux") {
+			const fallbackResult = await trySaveWithSecretServiceFallback(accountId, serialized);
+			if (fallbackResult.ok) return;
+			throw createLinuxSecureStoreUnavailableError(`Native backend could not create the credential entry (${getErrorMessage(error)}). Fallback secret-service backend also failed (${getErrorMessage(fallbackResult.error)}).`);
+		}
+		if (kind === "store_unavailable") throw createLinuxSecureStoreUnavailableError(getErrorMessage(error));
+		throw error;
+	}
 };
-const saveLinuxCrossKeychainPayload = async (accountId, payload) => withService$1(accountId, (service) => setPassword(service, accountId, JSON.stringify(payload)), { forWrite: true });
 const loadLinuxCrossKeychainPayload = async (accountId) => {
-	const raw = await withService$1(accountId, (service) => getPassword(service, accountId));
-	if (raw === null) throw new Error(`No stored credentials found for account ${accountId}.`);
-	return parsePayload$2(accountId, raw);
+	try {
+		const raw = await withService$1(accountId, (service) => getPassword(service, accountId));
+		if (raw === null) throw new Error(`No stored credentials found for account ${accountId}.`);
+		return parsePayload$2(accountId, raw);
+	} catch (error) {
+		if (classifyLinuxSecureStoreError(error) === "missing_entry") throw new Error(`No stored credentials found for account ${accountId}.`);
+		throw error;
+	}
+};
+const deleteLinuxCrossKeychainPayload = async (accountId) => {
+	try {
+		await withService$1(accountId, (service) => deletePassword(service, accountId));
+	} catch (error) {
+		if (classifyLinuxSecureStoreError(error) === "missing_entry") return;
+		throw error;
+	}
+};
+const linuxCrossKeychainPayloadExists = async (accountId) => {
+	try {
+		return await withService$1(accountId, async (service) => await getPassword(service, accountId) !== null);
+	} catch (error) {
+		if (classifyLinuxSecureStoreError(error) === "missing_entry") return false;
+		throw error;
+	}
 };
-const deleteLinuxCrossKeychainPayload = async (accountId) => withService$1(accountId, (service) => deletePassword(service, accountId));
-const linuxCrossKeychainPayloadExists = async (accountId) => withService$1(accountId, async (service) => await getPassword(service, accountId) !== null);
 
 //#endregion
 //#region lib/secrets/macos-cross-keychain.ts
@@ -775,13 +1063,16 @@ const windowsCrossKeychainPayloadExists = async (accountId) => withWindowsBacken
 //#endregion
 //#region lib/secrets/store.ts
 const MISSING_SECRET_STORE_ERROR_MARKERS = [
-	"No stored credentials found",
-	"No Keychain payload found",
-	"Password not found"
+	"no stored credentials found",
+	"no keychain payload found",
+	"password not found",
+	"no matching entry found in secure storage",
+	"no result found"
 ];
 const isMissingSecretStoreEntryError = (error) => {
 	if (!(error instanceof Error)) return false;
-	return MISSING_SECRET_STORE_ERROR_MARKERS.some((marker) => error.message.includes(marker));
+	const message = error.message.toLowerCase();
+	return MISSING_SECRET_STORE_ERROR_MARKERS.some((marker) => message.includes(marker));
 };
 const createMissingSecretStoreEntryError = (accountId) => /* @__PURE__ */ new Error(`No stored credentials found for account ${accountId}.`);
 const CACHED_ADAPTER_SYMBOL = Symbol.for("cdx.secretStore.cachedAdapter");
@@ -1467,33 +1758,19 @@ const promptBrowserFallbackChoice = async () => {
 	if (!process.stdin.isTTY || !process.stdout.isTTY) {
 		const selected = remoteHint ? "device" : "manual";
 		p.log.info(`Non-interactive terminal detected. Falling back to ${selected === "device" ? "device OAuth flow" : "manual URL copy/paste flow"}.`);
+		if (selected === "device") p.log.info("When interactive, manual URL copy/paste flow is recommended because device flow may be blocked by Cloudflare on some VPS/server IPs.");
 		return selected;
 	}
-	const options = remoteHint ? [
-		{
-			value: "device",
-			label: "Use device OAuth flow",
-			hint: "Recommended on SSH/remote servers"
-		},
-		{
-			value: "manual",
-			label: "Finish manually by copying URL",
-			hint: "Open URL on any machine and paste callback URL/code back here"
-		},
-		{
-			value: "cancel",
-			label: "Cancel login"
-		}
-	] : [
+	const options = [
 		{
 			value: "manual",
-			label: "Finish manually by copying URL",
-			hint: "Open URL on any machine and paste callback URL/code back here"
+			label: "Finish manually by copying URL (recommended)",
+			hint: remoteHint ? "Best on SSH/VPS: open URL on any machine and paste callback URL/code back here" : "Open URL on any machine and paste callback URL/code back here"
 		},
 		{
 			value: "device",
 			label: "Use device OAuth flow",
-			hint: "Best for headless/remote environments"
+			hint: "May fail on some VPS/servers due to Cloudflare challenge"
 		},
 		{
 			value: "cancel",
@@ -1535,10 +1812,33 @@ const promptPortConflictChoice = async (listeningProcess) => {
 	if (p.isCancel(selection)) return "cancel";
 	return selection;
 };
+const maybeCopyAuthorizationUrlToClipboard = async (authorizationUrl) => {
+	if (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)) {
+		const shouldCopy = await p.confirm({
+			message: "Copy login URL to clipboard now?",
+			initialValue: true
+		});
+		if (p.isCancel(shouldCopy) || !shouldCopy) return;
+	}
+	const copyResult = tryCopyToClipboard(authorizationUrl);
+	if (copyResult.ok) {
+		p.log.success(`Copied login URL to clipboard via ${copyResult.method}.`);
+		if (copyResult.warning) {
+			p.log.warning(copyResult.warning);
+			const helper = buildClipboardHelperCommand(authorizationUrl);
+			if (helper) p.log.message(`If needed, run this copy command instead:\n${helper}`);
+		}
+		return;
+	}
+	p.log.warning(`Could not copy login URL automatically${copyResult.error ? ` (${copyResult.error})` : ""}.`);
+	const helper = buildClipboardHelperCommand(authorizationUrl);
+	if (helper) p.log.message(`Try this copy command:\n${helper}`);
+};
 const promptManualAuthorizationCode = async (authorizationUrl, expectedState) => {
 	p.log.info("Manual login selected.");
 	p.log.message(`Open this URL in a browser:\n${authorizationUrl}`);
 	p.log.message("After approving, copy the full callback URL (or just the 'code' value) and paste it below.");
+	await maybeCopyAuthorizationUrlToClipboard(authorizationUrl);
 	for (let attempt = 1; attempt <= 3; attempt += 1) {
 		const response = await p.text({
 			message: "Paste callback URL or authorization code:",
@@ -1563,6 +1863,8 @@ const promptManualAuthorizationCode = async (authorizationUrl, expectedState) =>
 	return null;
 };
 const runDeviceOAuthFlow = async (useSpinner) => {
+	p.log.info("Device OAuth flow may fail on some VPS/servers because auth.openai.com can return a Cloudflare challenge.");
+	p.log.info("Recommended alternative: run login without --device-flow and use manual URL copy/paste callback completion.");
 	const deviceFlowResult = await startDeviceAuthorizationFlow();
 	if (deviceFlowResult.type !== "success") {
 		p.log.error("Device OAuth flow is not available right now.");
@@ -2413,6 +2715,56 @@ const getKeychainDecryptAccessByServiceAsync = async (services) => {
 	return parseKeychainDecryptAccessFromDump(dumpResult.output, dedupedServices);
 };
 
+//#endregion
+//#region lib/secrets/probe.ts
+const toError = (error) => error instanceof Error ? error : new Error(String(error));
+const createProbePayload = (accountId, now) => ({
+	refresh: `probe-refresh-${accountId}`,
+	access: `probe-access-${accountId}`,
+	expires: now + 6e4,
+	accountId
+});
+const payloadMatches = (expected, actual) => expected.accountId === actual.accountId && expected.refresh === actual.refresh && expected.access === actual.access && expected.expires === actual.expires;
+const runSecretStoreWriteReadProbe = async (secretStore, options = {}) => {
+	const probeAccountId = options.probeAccountId ?? `cdx-doctor-probe-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+	const payload = createProbePayload(probeAccountId, options.now ?? Date.now());
+	let saveSucceeded = false;
+	let result = { ok: true };
+	try {
+		await secretStore.save(probeAccountId, payload);
+		saveSucceeded = true;
+	} catch (error) {
+		result = {
+			ok: false,
+			stage: "save",
+			error: toError(error)
+		};
+	}
+	if (result.ok) try {
+		if (!payloadMatches(payload, await secretStore.load(probeAccountId))) result = {
+			ok: false,
+			stage: "verify",
+			error: /* @__PURE__ */ new Error("Secure-store probe loaded payload does not match the saved payload.")
+		};
+	} catch (error) {
+		result = {
+			ok: false,
+			stage: "load",
+			error: toError(error)
+		};
+	}
+	if (saveSucceeded) try {
+		await secretStore.delete(probeAccountId);
+	} catch (error) {
+		if (result.ok) result = {
+			ok: false,
+			stage: "delete",
+			error: toError(error)
+		};
+	}
+	return result;
+};
+
 //#endregion
 //#region lib/commands/doctor.ts
 const hasRuntimeTrustedApp = (trustedApplications, runtimeExecutablePath) => {
@@ -2422,6 +2774,23 @@ const hasRuntimeTrustedApp = (trustedApplications, runtimeExecutablePath) => {
 		return path.basename(trustedApp).toLowerCase() === runtimeBaseName;
 	});
 };
+const getSecretStoreProbeHeading = (platform) => {
+	if (platform === "linux") return "Linux secure-store probe";
+	if (platform === "darwin") return "macOS secure-store probe";
+	if (platform === "win32") return "Windows secure-store probe";
+	return null;
+};
+const createProbeAdapterForCurrentPlatform = () => {
+	const currentAdapter = getSecretStoreAdapter();
+	if (process.platform === "darwin" && currentAdapter.id === "macos-legacy-keychain") return createSecretStoreAdapterFromSelection("legacy-keychain", "darwin");
+	return createRuntimeSecretStoreAdapter(process.platform);
+};
+const getSecretStoreProbeGuidance = (platform) => {
+	if (platform === "linux") return "Suggested fix: ensure Secret Service is running/unlocked (for example gnome-keyring + secret-tool), then retry login.";
+	if (platform === "darwin") return "Suggested fix: ensure Keychain Access is unlocked and allows this runtime/toolchain to store/read passwords, then retry login.";
+	if (platform === "win32") return "Suggested fix: ensure Windows Credential Manager is available for this user session, then retry login.";
+	return null;
+};
 const registerDoctorCommand = (program) => {
 	program.command("doctor").description("Show auth file paths and runtime capabilities").option("--check-keychain-acl", "Run keychain trusted-app/ACL checks on macOS (can be slow)").action(async (options) => {
 		try {
@@ -2472,6 +2841,17 @@ const registerDoctorCommand = (program) => {
 					process.stdout.write(`  Summary: ${okCount}/${status.accounts.length} configured account(s) passed secure-store load checks.\n`);
 				}
 			}
+			const probeHeading = getSecretStoreProbeHeading(process.platform);
+			if (probeHeading) {
+				process.stdout.write(`\n${probeHeading}:\n`);
+				const probeResult = await runSecretStoreWriteReadProbe(createProbeAdapterForCurrentPlatform());
+				if (probeResult.ok) process.stdout.write("  write/read/delete probe: OK\n");
+				else {
+					process.stdout.write(`  ⚠ ${probeResult.stage} failed: ${probeResult.error.message}\n`);
+					const guidance = getSecretStoreProbeGuidance(process.platform);
+					if (guidance) process.stdout.write(`  ${guidance}\n`);
+				}
+			}
 			if (process.platform === "darwin" && !options.checkKeychainAcl) {
 				process.stdout.write("  ┌─ Optional keychain ACL check\n");
 				process.stdout.write("  │  Run: cdx doctor --check-keychain-acl\n");
@@ -2567,7 +2947,7 @@ const registerLabelCommand = (program) => {
 //#region lib/commands/login.ts
 const registerLoginCommand = (program, deps = {}) => {
 	const runLogin = deps.performLogin ?? performLogin;
-	program.command("login").description("Add a new OpenAI account via OAuth").option("--device-flow", "Use OAuth device flow instead of browser callback flow").action(async (options) => {
+	program.command("login").description("Add a new OpenAI account via OAuth").option("--device-flow", "Use OAuth device flow instead of browser callback flow (manual/browser flow is recommended; device flow may fail on some VPS due to Cloudflare)").action(async (options) => {
 		try {
 			if (!await runLogin({ authFlow: options.deviceFlow ? "device" : "auto" })) {
 				process.stderr.write("Login failed.\n");
@@ -2719,7 +3099,7 @@ const writeUpdatedAuthSummary = (result) => {
 //#endregion
 //#region lib/commands/refresh.ts
 const registerReloginCommand = (program) => {
-	program.command("relogin").description("Re-authenticate an existing account with full OAuth login (no duplicate account)").option("--device-flow", "Use OAuth device flow instead of browser callback flow").argument("[account]", "Account ID or label to re-login").action(async (account, options) => {
+	program.command("relogin").description("Re-authenticate an existing account with full OAuth login (no duplicate account)").option("--device-flow", "Use OAuth device flow instead of browser callback flow (manual/browser flow is recommended; device flow may fail on some VPS due to Cloudflare)").argument("[account]", "Account ID or label to re-login").action(async (account, options) => {
 		try {
 			const authFlow = options.deviceFlow ? "device" : "auto";
 			if (account) {
@@ -3043,6 +3423,189 @@ const registerUsageCommand = (program) => {
 	});
 };
 
+//#endregion
+//#region lib/runtime/update-manager.ts
+const detectRuntime = (input = {}) => {
+	const hasDenoGlobal = input.hasDenoGlobal ?? ("Deno" in globalThis && typeof globalThis.Deno !== "undefined");
+	const versions = input.versions ?? process.versions;
+	if (hasDenoGlobal) return "deno";
+	if (typeof versions.bun === "string" && versions.bun.length > 0) return "bun";
+	if (typeof versions.node === "string" && versions.node.length > 0) return "node";
+	return "unknown";
+};
+const normalizePath = (value) => value.replaceAll("\\", "/").toLowerCase();
+const detectInstallManagerFromPath = (executablePath) => {
+	if (!executablePath) return "unknown";
+	const normalizedPath = normalizePath(executablePath);
+	if (normalizedPath.includes("/.bun/install/global/node_modules/")) return "bun";
+	if (normalizedPath.includes("/lib/node_modules/") || normalizedPath.includes("/npm/node_modules/")) return "npm";
+	if (normalizedPath.includes("/.deno/") || normalizedPath.includes("/deno/bin/")) return "deno";
+	return "unknown";
+};
+const classifyInstallContextFromPath = (executablePath) => {
+	if (!executablePath) return "unknown";
+	if (detectInstallManagerFromPath(executablePath) !== "unknown") return "global";
+	const normalizedPath = normalizePath(executablePath);
+	if (normalizedPath.endsWith("/cdx.ts") || normalizedPath.includes("/codex-switcher/") || normalizedPath.includes("/node_modules/.bin/")) return "local-or-dev";
+	return "unknown";
+};
+const resolveFromRuntime = (runtime) => {
+	if (runtime === "bun") return "bun";
+	if (runtime === "node") return "npm";
+	if (runtime === "deno") return "deno";
+	return null;
+};
+const resolveUpdateManager = (input) => {
+	if (input.requestedManager !== "auto") return {
+		ok: true,
+		manager: input.requestedManager,
+		source: "explicit"
+	};
+	if (input.installManager !== "unknown") return {
+		ok: true,
+		manager: input.installManager,
+		source: "install-manager"
+	};
+	const fromRuntime = resolveFromRuntime(input.runtime);
+	if (fromRuntime) return {
+		ok: true,
+		manager: fromRuntime,
+		source: "runtime"
+	};
+	return { ok: false };
+};
+const buildUpdateInstallCommand = (manager, packageName) => {
+	if (manager === "bun") return {
+		command: "bun",
+		args: [
+			"add",
+			"-g",
+			`${packageName}@latest`
+		]
+	};
+	if (manager === "npm") return {
+		command: "npm",
+		args: [
+			"i",
+			"-g",
+			`${packageName}@latest`
+		]
+	};
+	return {
+		command: "deno",
+		args: [
+			"install",
+			"-g",
+			"-f",
+			"-A",
+			"-n",
+			"cdx",
+			`npm:${packageName}@latest`
+		]
+	};
+};
+
+//#endregion
+//#region lib/commands/update-self.ts
+const PACKAGE_NAME = "@bjesuiter/codex-switcher";
+const quoteIfNeeded = (value) => {
+	if (value.includes(" ")) return JSON.stringify(value);
+	return value;
+};
+const formatShellCommand = (command, args) => [command, ...args].map(quoteIfNeeded).join(" ");
+const executeUpdate = async (command, args) => {
+	await new Promise((resolve, reject) => {
+		const child = spawn(command, args, { stdio: "inherit" });
+		child.once("error", (error) => {
+			reject(error);
+		});
+		child.once("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`Update command failed with exit code ${code ?? "unknown"}.`));
+		});
+	});
+};
+const registerUpdateSelfCommand = (program) => {
+	program.command("update-self").description("Update cdx to the latest version").option("--manager <manager>", "Select update manager (auto|bun|npm|deno)", "auto").option("--dry-run", "Print selected manager and update command without executing").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
+		try {
+			const requestedManager = options.manager ?? "auto";
+			if (![
+				"auto",
+				"bun",
+				"npm",
+				"deno"
+			].includes(requestedManager)) {
+				process.stderr.write(`Invalid value '${requestedManager}' for --manager. Allowed values: auto, bun, npm, deno.\n`);
+				process.exit(1);
+			}
+			const runtime = detectRuntime();
+			const executablePath = process.argv[1];
+			const installManager = detectInstallManagerFromPath(executablePath);
+			const installContext = classifyInstallContextFromPath(executablePath);
+			if (requestedManager === "auto" && installManager === "unknown" && installContext === "local-or-dev") {
+				process.stderr.write("Refusing to auto-update from a local/dev checkout. Re-run with --manager bun|npm|deno.\n");
+				process.exit(1);
+			}
+			const resolvedManager = resolveUpdateManager({
+				requestedManager,
+				runtime,
+				installManager
+			});
+			process.stdout.write(`Runtime: ${runtime}\n`);
+			process.stdout.write(`Detected install manager: ${installManager}\n`);
+			if (!resolvedManager.ok) {
+				process.stderr.write("Could not determine update manager automatically. Re-run with --manager bun|npm|deno.\n");
+				process.stderr.write("Manual update commands:\n");
+				process.stderr.write(`  bun: ${formatShellCommand("bun", [
+					"add",
+					"-g",
+					`${PACKAGE_NAME}@latest`
+				])}\n`);
+				process.stderr.write(`  npm: ${formatShellCommand("npm", [
+					"i",
+					"-g",
+					`${PACKAGE_NAME}@latest`
+				])}\n`);
+				process.stderr.write(`  deno: ${formatShellCommand("deno", [
+					"install",
+					"-g",
+					"-f",
+					"-A",
+					"-n",
+					"cdx",
+					`npm:${PACKAGE_NAME}@latest`
+				])}\n`);
+				process.exit(1);
+			}
+			const selectedManager = resolvedManager.manager;
+			const command = buildUpdateInstallCommand(selectedManager, PACKAGE_NAME);
+			const printableCommand = formatShellCommand(command.command, command.args);
+			process.stdout.write(`Selected manager: ${selectedManager}\n`);
+			process.stdout.write(`Source: ${resolvedManager.source}\n`);
+			process.stdout.write(`Command: ${printableCommand}\n`);
+			if (options.dryRun) return;
+			if (!options.yes) {
+				const confirmed = await p.confirm({
+					message: `Run update command now?\n${printableCommand}`,
+					initialValue: true
+				});
+				if (p.isCancel(confirmed) || !confirmed) {
+					process.stderr.write("Update cancelled.\n");
+					process.exit(1);
+				}
+			}
+			await executeUpdate(command.command, command.args);
+			process.stdout.write("Update completed.\n");
+			process.stdout.write("Run `cdx version` to verify the installed version.\n");
+		} catch (error) {
+			exitWithCommandError(error);
+		}
+	});
+};
+
 //#endregion
 //#region lib/commands/version.ts
 const registerVersionCommand = (program, version) => {
@@ -3162,6 +3725,7 @@ const createProgram = (deps = {}) => {
 	registerStatusCommand(program);
 	registerDoctorCommand(program);
 	registerUsageCommand(program);
+	registerUpdateSelfCommand(program);
 	registerHelpCommand(program);
 	registerVersionCommand(program, version);
 	registerDefaultInteractiveAction(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjesuiter/codex-switcher",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "type": "module",
   "description": "CLI tool to switch between multiple OpenAI accounts for OpenCode",
   "bin": {