statelyai 0.5.4 → 0.6.1

package/README.md

@@ -7,20 +7,33 @@ This package contains the `statelyai` command implementation.
 <!-- happy-path CLI usage and statelyai.json shape derived from packages/cli/src/cli.ts#COMMANDS and packages/cli/src/projectConfig.ts -->
 ## Happy Path
 
-1. Get an API key from [Stately API Key settings](https://stately.ai/registry/user/my-settings?tab=API+Key).
-2. Log in once:
+1. Log in once:
 
 ```bash
 statelyai login
 ```
 
-3. Initialize the current repo:
+Automation can set `STATELY_ACCESS_TOKEN` for OAuth, or pass `--api-key` /
+`STATELY_API_KEY` for legacy API-key commands.
+
+For a custom OAuth protected resource, discover OAuth from that resource:
+
+```bash
+statelyai login --base-url http://localhost:3000/registry/api/mcp
+```
+
+`statelyai login --auth bearer` uses the same browser OAuth flow explicitly.
+`statelyai login --api-key` keeps the legacy manual API-key path.
+`statelyai open` requires OAuth (`statelyai login` or `STATELY_ACCESS_TOKEN`);
+free accounts open read-only root-level views.
+
+2. Initialize the current repo:
 
 ```bash
 statelyai init
 ```
 
-4. Optionally scan the repo and save suggested source globs:
+3. Optionally scan the repo and save suggested source globs:
 
 ```bash
 statelyai init --scan
@@ -43,7 +56,7 @@ That writes a `statelyai.json` like:
 }
 ```
 
-5. Push local machines:
+4. Push local machines:
 
 ```bash
 statelyai push
@@ -57,7 +70,7 @@ statelyai push --dry-run
 
 If a saved `// @statelyai id=...` points to a deleted or inaccessible remote machine, `push` will prompt to relink the file as a new remote machine and replace the local id.
 
-6. Pull remote changes back into linked local files and create new local files for remote-only project machines when `newMachinesDir` is configured:
+5. Pull remote changes back into linked local files and create new local files for remote-only project machines when `newMachinesDir` is configured:
 
 ```bash
 statelyai pull

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { p as run } from "./cli-DB0A-O4Y.mjs";
+import { v as run } from "./cli-jiby9qdf.mjs";
 
 //#region src/bin.ts
 run();

package/dist/{cli-DB0A-O4Y.mjs → cli-jiby9qdf.mjs}

@@ -1,5 +1,7 @@
+import * as crypto from "node:crypto";
 import fs, { promises, watch } from "node:fs";
 import fsPromises from "node:fs/promises";
+import * as http from "node:http";
 import { execFile, execFileSync, spawn } from "node:child_process";
 import * as path$1 from "node:path";
 import path from "node:path";
@@ -8,10 +10,8 @@ import { Writable } from "node:stream";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { Args, Command, Flags, flush, handle, run } from "@oclif/core";
-import * as crypto from "node:crypto";
-import * as http from "node:http";
 import os from "node:os";
-import { StudioApiError, createStatelyClient, getStatelyPragma } from "@statelyai/sdk";
+import { StudioApiError, buildAuthorizeUrl, createPkcePair, createStatelyClient, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, getStatelyPragma, registerOAuthClient } from "@statelyai/sdk";
 import { planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
 
 //#region src/cliHost.ts
@@ -86,6 +86,7 @@ var RemoteEditorSession = class {
 	lastPersistedGraph;
 	currentSourceLocations;
 	currentFormat;
+	editorSyncAccess;
 	ready = false;
 	pendingMessages = [];
 	pendingRetrievals = /* @__PURE__ */ new Map();
@@ -146,13 +147,16 @@ var RemoteEditorSession = class {
 			const update = await this.parseRootDocument();
 			this.currentFormat = update.format;
 			this.currentSourceLocations = update.sourceLocations;
+			this.editorSyncAccess = update.access;
 			this.updateSourceLocations(update.sourceLocations);
 			this.postMessage({
 				type: "@statelyai.init",
 				machine: update.machine,
 				format: update.format,
 				sourceLocations: update.sourceLocations,
-				mode: "editing",
+				mode: update.access?.readOnly ? "viewing" : "editing",
+				readOnly: update.access?.readOnly,
+				capabilities: update.access?.capabilities,
 				theme: "light",
 				unsavedIndicator: { enabled: true },
 				leftPanels: [],
@@ -173,6 +177,7 @@ var RemoteEditorSession = class {
 			const update = await this.parseRootDocument();
 			this.currentFormat = update.format;
 			this.currentSourceLocations = update.sourceLocations;
+			this.editorSyncAccess = update.access ?? this.editorSyncAccess;
 			this.updateSourceLocations(update.sourceLocations);
 			this.postMessage({
 				type: "@statelyai.update",
@@ -185,6 +190,16 @@ var RemoteEditorSession = class {
 		}
 	}
 	async saveFromEditor(msg) {
+		if (this.editorSyncAccess?.readOnly) {
+			const message = "Your Stately plan allows read-only editor sync.";
+			this.postMessage({
+				type: "@statelyai.toast",
+				message,
+				toastType: "error"
+			});
+			this.showError(message);
+			return;
+		}
 		const validationErrors = getValidationErrors(msg.validations);
 		if (validationErrors.length > 0) {
 			const message = formatValidationErrorMessage(validationErrors);
@@ -701,36 +716,109 @@ function getCredentialsFilePath() {
 	return path.join(getConfigDir(), CREDENTIALS_FILE_NAME);
 }
 function shouldUseFileBackendOnly() {
-	return process.env.STATELYAI_CREDENTIALS_BACKEND === "file";
+	return process.env.STATELYAI_CREDENTIALS_BACKEND === "file" || process.env.STATELYAI_CONFIG_DIR !== void 0;
 }
 async function readFileCredentials() {
+	const storedCredential = await readFileStoredCredential();
+	if (storedCredential?.credential?.type !== "api_key") return;
+	return {
+		apiKey: storedCredential.credential.token,
+		backend: storedCredential.backend,
+		location: storedCredential.location
+	};
+}
+function parseStoredCredential(raw, backend, location) {
 	try {
-		const raw = await promises.readFile(getCredentialsFilePath(), "utf8");
 		const parsed = JSON.parse(raw);
-		if (typeof parsed.apiKey !== "string" || parsed.apiKey.length === 0) return;
+		if (typeof parsed.apiKey === "string" && parsed.apiKey.length > 0) return {
+			credential: {
+				type: "api_key",
+				token: parsed.apiKey
+			},
+			backend,
+			location
+		};
+		if (parsed.authMode === "none") return {
+			authMode: "none",
+			backend,
+			location
+		};
+		if (typeof parsed.credential === "object" && parsed.credential !== null && "type" in parsed.credential) {
+			const credential = parsed.credential;
+			if (credential.type === "api_key" && typeof credential.token === "string" && credential.token.length > 0) return {
+				credential: {
+					type: "api_key",
+					token: credential.token
+				},
+				backend,
+				location
+			};
+			if (credential.type === "oauth" && typeof credential.accessToken === "string" && credential.accessToken.length > 0) return {
+				credential: {
+					type: "oauth",
+					accessToken: credential.accessToken,
+					...typeof credential.refreshToken === "string" ? { refreshToken: credential.refreshToken } : {},
+					...typeof credential.expiresAt === "number" ? { expiresAt: credential.expiresAt } : {}
+				},
+				backend,
+				location
+			};
+		}
+		return;
+	} catch {
+		const token = raw.trim();
+		if (!token) return;
 		return {
-			apiKey: parsed.apiKey,
-			backend: "file",
-			location: getCredentialsFilePath()
+			credential: {
+				type: "api_key",
+				token
+			},
+			backend,
+			location
 		};
+	}
+}
+async function readFileStoredCredential() {
+	try {
+		const credentialsPath = getCredentialsFilePath();
+		return parseStoredCredential(await promises.readFile(credentialsPath, "utf8"), "file", credentialsPath);
 	} catch {
 		return;
 	}
 }
 async function writeFileCredentials(apiKey) {
+	const stored = await writeFileStoredCredential({
+		type: "api_key",
+		token: apiKey
+	});
+	return {
+		apiKey,
+		backend: stored.backend,
+		location: stored.location
+	};
+}
+async function writeFileStoredCredential(credential, authMode) {
 	const configDir = getConfigDir();
 	const credentialsPath = getCredentialsFilePath();
+	const payload = authMode === "none" ? {
+		version: 1,
+		authMode: "none"
+	} : {
+		version: 1,
+		credential
+	};
 	await promises.mkdir(configDir, {
 		recursive: true,
 		mode: 448
 	});
-	await promises.writeFile(credentialsPath, `${JSON.stringify({ apiKey }, null, 2)}\n`, {
+	await promises.writeFile(credentialsPath, `${JSON.stringify(payload, null, 2)}\n`, {
 		encoding: "utf8",
 		mode: 384
 	});
 	await promises.chmod(credentialsPath, 384);
 	return {
-		apiKey,
+		...credential ? { credential } : {},
+		...authMode ? { authMode } : {},
 		backend: "file",
 		location: credentialsPath
 	};
@@ -744,6 +832,15 @@ async function deleteFileCredentials() {
 	}
 }
 async function readMacOSKeychain() {
+	const storedCredential = await readMacOSStoredCredential();
+	if (storedCredential?.credential?.type !== "api_key") return;
+	return {
+		apiKey: storedCredential.credential.token,
+		backend: storedCredential.backend,
+		location: storedCredential.location
+	};
+}
+async function readMacOSStoredCredential() {
 	if (process.platform !== "darwin") return;
 	try {
 		const { stdout } = await execFile$1("security", [
@@ -754,19 +851,31 @@ async function readMacOSKeychain() {
 			ACCOUNT_NAME,
 			"-w"
 		]);
-		const apiKey = stdout.trim();
-		if (!apiKey) return;
-		return {
-			apiKey,
-			backend: "macos-keychain",
-			location: "macOS Keychain"
-		};
+		return parseStoredCredential(stdout, "macos-keychain", "macOS Keychain");
 	} catch {
 		return;
 	}
 }
 async function writeMacOSKeychain(apiKey) {
+	const stored = await writeMacOSStoredCredential({
+		type: "api_key",
+		token: apiKey
+	});
+	return stored ? {
+		apiKey,
+		backend: stored.backend,
+		location: stored.location
+	} : void 0;
+}
+async function writeMacOSStoredCredential(credential, authMode) {
 	if (process.platform !== "darwin") return;
+	const payload = authMode === "none" ? {
+		version: 1,
+		authMode: "none"
+	} : {
+		version: 1,
+		credential
+	};
 	try {
 		await execFile$1("security", [
 			"add-generic-password",
@@ -776,10 +885,11 @@ async function writeMacOSKeychain(apiKey) {
 			"-a",
 			ACCOUNT_NAME,
 			"-w",
-			apiKey
+			JSON.stringify(payload)
 		]);
 		return {
-			apiKey,
+			...credential ? { credential } : {},
+			...authMode ? { authMode } : {},
 			backend: "macos-keychain",
 			location: "macOS Keychain"
 		};
@@ -803,6 +913,15 @@ async function deleteMacOSKeychain() {
 	}
 }
 async function readLinuxSecretTool() {
+	const storedCredential = await readLinuxStoredCredential();
+	if (storedCredential?.credential?.type !== "api_key") return;
+	return {
+		apiKey: storedCredential.credential.token,
+		backend: storedCredential.backend,
+		location: storedCredential.location
+	};
+}
+async function readLinuxStoredCredential() {
 	if (process.platform !== "linux") return;
 	try {
 		const { stdout } = await execFile$1("secret-tool", [
@@ -812,19 +931,31 @@ async function readLinuxSecretTool() {
 			"account",
 			ACCOUNT_NAME
 		]);
-		const apiKey = stdout.trim();
-		if (!apiKey) return;
-		return {
-			apiKey,
-			backend: "linux-secret-tool",
-			location: "Secret Service (secret-tool)"
-		};
+		return parseStoredCredential(stdout, "linux-secret-tool", "Secret Service (secret-tool)");
 	} catch {
 		return;
 	}
 }
 async function writeLinuxSecretTool(apiKey) {
+	const stored = await writeLinuxStoredCredential({
+		type: "api_key",
+		token: apiKey
+	});
+	return stored ? {
+		apiKey,
+		backend: stored.backend,
+		location: stored.location
+	} : void 0;
+}
+async function writeLinuxStoredCredential(credential, authMode) {
 	if (process.platform !== "linux") return;
+	const payload = authMode === "none" ? {
+		version: 1,
+		authMode: "none"
+	} : {
+		version: 1,
+		credential
+	};
 	try {
 		execFileSync("secret-tool", [
 			"store",
@@ -834,9 +965,10 @@ async function writeLinuxSecretTool(apiKey) {
 			SERVICE_NAME,
 			"account",
 			ACCOUNT_NAME
-		], { input: apiKey });
+		], { input: JSON.stringify(payload) });
 		return {
-			apiKey,
+			...credential ? { credential } : {},
+			...authMode ? { authMode } : {},
 			backend: "linux-secret-tool",
 			location: "Secret Service (secret-tool)"
 		};
@@ -863,10 +995,22 @@ async function getStoredApiKey() {
 	if (shouldUseFileBackendOnly()) return readFileCredentials();
 	return await readMacOSKeychain() ?? await readLinuxSecretTool() ?? await readFileCredentials();
 }
+async function getStoredCredential() {
+	if (shouldUseFileBackendOnly()) return readFileStoredCredential();
+	return await readMacOSStoredCredential() ?? await readLinuxStoredCredential() ?? await readFileStoredCredential();
+}
 async function setStoredApiKey(apiKey) {
 	if (shouldUseFileBackendOnly()) return writeFileCredentials(apiKey);
 	return await writeMacOSKeychain(apiKey) ?? await writeLinuxSecretTool(apiKey) ?? await writeFileCredentials(apiKey);
 }
+async function setStoredCredential(credential) {
+	if (shouldUseFileBackendOnly()) return writeFileStoredCredential(credential);
+	return await writeMacOSStoredCredential(credential) ?? await writeLinuxStoredCredential(credential) ?? await writeFileStoredCredential(credential);
+}
+async function setStoredNoAuth() {
+	if (shouldUseFileBackendOnly()) return writeFileStoredCredential(void 0, "none");
+	return await writeMacOSStoredCredential(void 0, "none") ?? await writeLinuxStoredCredential(void 0, "none") ?? await writeFileStoredCredential(void 0, "none");
+}
 async function deleteStoredApiKey() {
 	if (shouldUseFileBackendOnly()) {
 		const deleted = await deleteFileCredentials();
@@ -1168,6 +1312,11 @@ function loadLocalEnv() {
 }
 loadLocalEnv();
 function getEnvApiKey() {
+	const accessToken = process.env.STATELY_ACCESS_TOKEN;
+	if (accessToken) return {
+		apiKey: accessToken,
+		variable: "STATELY_ACCESS_TOKEN"
+	};
 	const statelyApiKey = process.env.STATELY_API_KEY;
 	if (statelyApiKey) return {
 		apiKey: statelyApiKey,
@@ -1179,6 +1328,32 @@ function getEnvApiKey() {
 		variable: "NEXT_PUBLIC_STATELY_API_KEY"
 	};
 }
+function getEnvCredential() {
+	const accessToken = process.env.STATELY_ACCESS_TOKEN;
+	if (accessToken) return {
+		credential: {
+			type: "oauth",
+			accessToken
+		},
+		variable: "STATELY_ACCESS_TOKEN"
+	};
+	const statelyApiKey = process.env.STATELY_API_KEY;
+	if (statelyApiKey) return {
+		credential: {
+			type: "api_key",
+			token: statelyApiKey
+		},
+		variable: "STATELY_API_KEY"
+	};
+	const publicApiKey = process.env.NEXT_PUBLIC_STATELY_API_KEY;
+	if (publicApiKey) return {
+		credential: {
+			type: "api_key",
+			token: publicApiKey
+		},
+		variable: "NEXT_PUBLIC_STATELY_API_KEY"
+	};
+}
 async function resolveApiKey(explicitApiKey) {
 	if (explicitApiKey) return {
 		apiKey: explicitApiKey,
@@ -1199,6 +1374,23 @@ async function resolveApiKey(explicitApiKey) {
 	};
 	return { source: "missing" };
 }
+async function resolveOAuthAccessToken() {
+	const envCredential = getEnvCredential();
+	if (envCredential?.credential.type === "oauth") return {
+		apiKey: envCredential.credential.accessToken,
+		source: "env",
+		detail: envCredential.variable
+	};
+	if (envCredential?.credential.type === "api_key") throw new Error("`statelyai open` requires OAuth login. Run `statelyai login` instead of using an API key.");
+	const storedCredential = await getStoredCredential();
+	if (storedCredential?.credential?.type === "oauth") return {
+		apiKey: storedCredential.credential.accessToken,
+		source: "stored",
+		detail: describeCredentialBackend(storedCredential.backend, storedCredential.location)
+	};
+	if (storedCredential?.credential?.type === "api_key") throw new Error("`statelyai open` requires OAuth login. Run `statelyai login` to replace the stored API key.");
+	return { source: "missing" };
+}
 function getDefaultBaseUrl() {
 	return process.env.STATELY_API_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? process.env.NEXT_PUBLIC_STATELY_API_URL;
 }
@@ -1208,6 +1400,51 @@ function getDefaultEditorUrl() {
 function getResolvedStudioUrl(baseUrl) {
 	return baseUrl ?? getDefaultBaseUrl() ?? "https://stately.ai";
 }
+function getDefaultOAuthIssuer() {
+	return process.env.STATELY_OAUTH_ISSUER ?? process.env.NEXT_PUBLIC_STATELY_OAUTH_ISSUER ?? "https://stately.ai";
+}
+function normalizeLoginResourceUrl(baseUrl) {
+	const raw = baseUrl;
+	const url = new URL(raw);
+	if (url.pathname === "/" || url.pathname === "") url.pathname = "/api/mcp";
+	return url.toString();
+}
+function getConfiguredOauthClientId() {
+	return process.env.STATELY_OAUTH_CLIENT_ID ?? process.env.NEXT_PUBLIC_STATELY_OAUTH_CLIENT_ID;
+}
+async function discoverOAuthLogin(options = {}) {
+	const resourceUrl = options.baseUrl ? normalizeLoginResourceUrl(options.baseUrl) : getDefaultOAuthIssuer();
+	const protectedResource = options.baseUrl ? await discoverProtectedResource(resourceUrl, { fetch: options.fetch }) : void 0;
+	const issuer = protectedResource ? protectedResource.authorization_servers?.[0] : resourceUrl;
+	if (!issuer) throw new Error(`No OAuth authorization server advertised by ${resourceUrl}. Pass --base-url for a Stately OAuth-enabled resource or set STATELY_OAUTH_ISSUER.`);
+	const authorizationServer = await discoverAuthorizationServer(issuer, { fetch: options.fetch });
+	const authorizationEndpoint = authorizationServer.authorization_endpoint;
+	const tokenEndpoint = authorizationServer.token_endpoint;
+	if (!authorizationEndpoint || !tokenEndpoint) throw new Error(`Authorization server ${issuer} did not advertise authorization and token endpoints.`);
+	const configuredClientId = options.clientId ?? getConfiguredOauthClientId();
+	const scopes = protectedResource?.scopes_supported ?? [];
+	let clientId = configuredClientId;
+	if (!clientId && authorizationServer.registration_endpoint && options.redirectUri) try {
+		clientId = (await registerOAuthClient({
+			registrationEndpoint: authorizationServer.registration_endpoint,
+			redirectUri: options.redirectUri,
+			scopes,
+			fetch: options.fetch
+		})).client_id;
+	} catch (error) {
+		throw new Error(`OAuth dynamic client registration failed for ${authorizationServer.registration_endpoint}. Enable dynamic client registration on the OAuth authorization server, or set STATELY_OAUTH_CLIENT_ID to a registered OAuth client id.`, { cause: error });
+	}
+	if (!clientId) throw new Error(`Authorization server ${issuer} did not advertise dynamic client registration. Set STATELY_OAUTH_CLIENT_ID to a registered OAuth client id.`);
+	return {
+		authorizationServer,
+		authorizationEndpoint,
+		clientId,
+		...protectedResource ? { protectedResource } : {},
+		resourceUrl,
+		scopes,
+		tokenEndpoint
+	};
+}
 function parseGitHubRemote(remoteUrl) {
 	const httpsMatch = remoteUrl.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
 	if (httpsMatch) {
@@ -1289,6 +1526,148 @@ async function promptForApiKey() {
 		rl.close();
 	}
 }
+async function promptForOAuthCallback() {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("No interactive terminal available to paste the OAuth callback URL.");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		terminal: true
+	});
+	try {
+		return (await rl.question("Paste the callback URL or code: ")).trim();
+	} finally {
+		rl.close();
+	}
+}
+function parseOAuthCallback(value) {
+	try {
+		const url = new URL(value);
+		const code = url.searchParams.get("code");
+		const state = url.searchParams.get("state") ?? void 0;
+		if (!code) throw new Error("Callback URL did not include a code parameter.");
+		return {
+			code,
+			state
+		};
+	} catch (error) {
+		if (error instanceof Error && error.message.includes("code parameter")) throw error;
+		if (!value) throw new Error("OAuth code cannot be empty.");
+		return { code: value };
+	}
+}
+function createOAuthCredential(tokenResponse, now = Date.now()) {
+	if (!tokenResponse.access_token) throw new Error("Token response did not include an access_token.");
+	const expiresAt = typeof tokenResponse.expires_at === "number" ? tokenResponse.expires_at * 1e3 : typeof tokenResponse.expires_in === "number" ? now + tokenResponse.expires_in * 1e3 : void 0;
+	return {
+		type: "oauth",
+		accessToken: tokenResponse.access_token,
+		...tokenResponse.refresh_token ? { refreshToken: tokenResponse.refresh_token } : {},
+		...expiresAt ? { expiresAt } : {}
+	};
+}
+async function createLocalOAuthCallbackServer(options) {
+	let resolveCode;
+	let rejectCode;
+	const codePromise = new Promise((resolve, reject) => {
+		resolveCode = resolve;
+		rejectCode = reject;
+	});
+	const server = http.createServer((req, res) => {
+		const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+		const code = requestUrl.searchParams.get("code");
+		const state = requestUrl.searchParams.get("state");
+		const error = requestUrl.searchParams.get("error");
+		res.setHeader("Content-Type", "text/html; charset=utf-8");
+		if (error) {
+			res.statusCode = 400;
+			res.end("<!doctype html><title>Sign in failed</title><p>Sign in failed. Return to the terminal.</p>");
+			rejectCode(new Error(error));
+			return;
+		}
+		if (!code || state !== options.state) {
+			res.statusCode = 400;
+			res.end("<!doctype html><title>Sign in failed</title><p>Invalid sign-in callback. Return to the terminal.</p>");
+			rejectCode(/* @__PURE__ */ new Error("Invalid OAuth callback."));
+			return;
+		}
+		res.end("<!doctype html><title>Signed in</title><p>Signed in. You can close this window.</p>");
+		resolveCode(code);
+	});
+	await new Promise((resolve) => {
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Could not start OAuth callback server.");
+	return {
+		redirectUri: `http://127.0.0.1:${address.port}/callback`,
+		waitForCode: () => codePromise,
+		close: () => new Promise((resolve) => {
+			server.close(() => resolve());
+		})
+	};
+}
+async function buildOAuthLoginStart(options) {
+	const [discovery, pkce] = await Promise.all([discoverOAuthLogin({
+		baseUrl: options.baseUrl,
+		clientId: options.clientId,
+		fetch: options.fetch,
+		redirectUri: options.redirectUri
+	}), createPkcePair()]);
+	return {
+		authorizeUrl: buildAuthorizeUrl({
+			authorizationEndpoint: discovery.authorizationEndpoint,
+			clientId: discovery.clientId,
+			redirectUri: options.redirectUri,
+			codeChallenge: pkce.codeChallenge,
+			state: options.state,
+			scopes: discovery.scopes
+		}),
+		codeVerifier: pkce.codeVerifier,
+		discovery
+	};
+}
+function formatStoredCredentialSource(storedCredential) {
+	if (storedCredential.credential?.type === "api_key") return `Credential source: stored api_key (${describeCredentialBackend(storedCredential.backend, storedCredential.location)}).`;
+	if (storedCredential.credential?.type === "oauth") return `Credential source: stored oauth (${describeCredentialBackend(storedCredential.backend, storedCredential.location)}).`;
+	if (storedCredential.authMode === "none") return `Credential source: stored no-auth mode (${describeCredentialBackend(storedCredential.backend, storedCredential.location)}).`;
+	return `Credential source: stored unknown (${describeCredentialBackend(storedCredential.backend, storedCredential.location)}).`;
+}
+async function runOAuthBrowserLogin(options) {
+	const state = crypto.randomBytes(16).toString("base64url");
+	const callbackServer = await createLocalOAuthCallbackServer({ state });
+	try {
+		const { authorizeUrl, codeVerifier, discovery } = await buildOAuthLoginStart({
+			baseUrl: options.baseUrl,
+			redirectUri: callbackServer.redirectUri,
+			state
+		});
+		options.log(`Opening browser for ${discovery.resourceUrl}`);
+		options.log(authorizeUrl);
+		let openedBrowser = false;
+		try {
+			openBrowser(authorizeUrl);
+			openedBrowser = true;
+		} catch {
+			options.log("Could not open a browser automatically.");
+		}
+		const codePromise = callbackServer.waitForCode();
+		const pastedCodePromise = !openedBrowser && process.stdin.isTTY && process.stdout.isTTY ? promptForOAuthCallback().then((value) => {
+			const callback = parseOAuthCallback(value);
+			if (callback.state && callback.state !== state) throw new Error("OAuth state did not match.");
+			return callback.code;
+		}) : void 0;
+		const code = await (pastedCodePromise ? Promise.race([codePromise, pastedCodePromise]) : codePromise);
+		return setStoredCredential(createOAuthCredential(await exchangeCodeForToken({
+			tokenEndpoint: discovery.tokenEndpoint,
+			code,
+			codeVerifier,
+			redirectUri: callbackServer.redirectUri,
+			clientId: discovery.clientId
+		})));
+	} finally {
+		await callbackServer.close();
+	}
+}
 async function promptYesNo(question, defaultValue = true) {
 	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("No interactive terminal available.");
 	const rl = createInterface({
@@ -1954,7 +2333,7 @@ var OpenCommand = class OpenCommand extends Command {
 	}) };
 	static flags = {
 		help: Flags.help({ char: "h" }),
-		"api-key": Flags.string({ description: "Stately API key used when the editor server requires auth" }),
+		"api-key": Flags.string({ description: "Deprecated. `statelyai open` requires OAuth login." }),
 		"editor-url": Flags.string({ description: "Base URL for the Stately editor embed" }),
 		host: Flags.string({
 			description: "Local server host",
@@ -1977,7 +2356,9 @@ var OpenCommand = class OpenCommand extends Command {
 	};
 	async run() {
 		const { args, flags } = await this.parse(OpenCommand);
-		const apiKey = (await resolveApiKey(flags["api-key"])).apiKey;
+		if (flags["api-key"]) throw new Error("`statelyai open` requires OAuth login. Run `statelyai login` and retry.");
+		const apiKey = (await resolveOAuthAccessToken()).apiKey;
+		if (!apiKey) throw new Error("`statelyai open` requires OAuth login. Run `statelyai login` and retry.");
 		await openEditor({
 			fileName: path.resolve(args.file),
 			editorUrl: flags["editor-url"] ?? getDefaultEditorUrl(),
@@ -2062,23 +2443,46 @@ var InitCommand = class InitCommand extends Command {
 };
 var LoginCommand = class LoginCommand extends Command {
 	static enableJsonFlag = false;
-	static summary = "Store a Stately API key for future CLI use.";
-	static description = "Stores a Stately API key in the OS credential store when available, with a private file fallback.";
+	static summary = "Store Stately credentials for future CLI use.";
+	static description = "Stores Stately credentials in the OS credential store when available, with a private file fallback.";
 	static flags = {
 		help: Flags.help({ char: "h" }),
 		"api-key": Flags.string({ description: "API key to store without an interactive prompt" }),
+		"base-url": Flags.string({ description: "OAuth protected-resource URL for custom deployments" }),
 		stdin: Flags.boolean({
 			description: "Read the API key from standard input",
 			default: false
+		}),
+		auth: Flags.string({
+			description: "Authentication mode for the target server",
+			options: ["none", "bearer"]
 		})
 	};
 	async run() {
 		const { flags } = await this.parse(LoginCommand);
+		if (flags["api-key"] && flags.auth === "bearer") this.error("Pass either --api-key or --auth bearer, not both.");
+		if (flags.auth === "none") {
+			if (flags.stdin || flags["api-key"]) this.error("Pass either --auth none or an API key, not both.");
+			const stored = await setStoredNoAuth();
+			this.log(`Stored no-auth mode in ${describeCredentialBackend(stored.backend, stored.location)}.`);
+			return;
+		}
+		if (!flags["api-key"] && !flags.stdin) {
+			const stored = await runOAuthBrowserLogin({
+				baseUrl: flags["base-url"],
+				log: (message) => this.log(message)
+			});
+			this.log(`Stored OAuth credential in ${describeCredentialBackend(stored.backend, stored.location)}.`);
+			return;
+		}
 		if (flags.stdin && flags["api-key"]) this.error("Pass either --api-key or --stdin, not both.");
 		if (!flags["api-key"] && !flags.stdin && process.stdin.isTTY && process.stdout.isTTY) this.log(`Get or create an API key at ${STATELY_API_KEY_SETTINGS_URL}`);
 		const apiKey = normalizeApiKey(flags["api-key"] ?? (!process.stdin.isTTY || flags.stdin ? await readApiKeyFromStdin() : await promptForApiKey()));
 		if (!apiKey) this.error(`API key cannot be empty.\nGet or create an API key at ${STATELY_API_KEY_SETTINGS_URL}`);
-		const stored = await setStoredApiKey(apiKey);
+		const stored = flags["api-key"] || flags.stdin ? await setStoredApiKey(apiKey) : await setStoredCredential({
+			type: "api_key",
+			token: apiKey
+		});
 		this.log(`Stored API key in ${describeCredentialBackend(stored.backend, stored.location)}.`);
 	}
 };
@@ -2102,15 +2506,20 @@ var WhoamiCommand = class extends Command {
 	static description = "Reports whether the CLI would use a flag, environment variable, or stored credential.";
 	static flags = { help: Flags.help({ char: "h" }) };
 	async run() {
-		const envApiKey = getEnvApiKey();
-		const storedApiKey = await getStoredApiKey();
-		if (envApiKey) {
-			this.log(`API key source: environment (${envApiKey.variable}).`);
+		const envCredential = getEnvCredential();
+		const storedCredential = await getStoredCredential();
+		const storedApiKey = storedCredential?.credential?.type === "api_key" ? {
+			apiKey: storedCredential.credential.token,
+			backend: storedCredential.backend,
+			location: storedCredential.location
+		} : void 0;
+		if (envCredential) {
+			this.log(`Credential source: environment ${envCredential.credential.type} (${envCredential.variable}).`);
 			if (storedApiKey) this.log(`Stored credential also available in ${describeCredentialBackend(storedApiKey.backend, storedApiKey.location)}.`);
 			return;
 		}
-		if (storedApiKey) {
-			this.log(`API key source: stored credential (${describeCredentialBackend(storedApiKey.backend, storedApiKey.location)}).`);
+		if (storedCredential) {
+			this.log(formatStoredCredentialSource(storedCredential));
 			return;
 		}
 		this.log(getMissingApiKeyMessage());
@@ -2149,4 +2558,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run$1();
 
 //#endregion
-export { formatMissingNewMachineDirMessage as a, inferInitProjectName as c, resolveApiKey as d, resolveConfiguredPullTargets as f, createStatelyProjectConfig as h, discoverRemoteProjectMachineTargets as i, initProject as l, scanProjectSources as m, classifyPushCandidates as n, formatPlanSummary as o, run$1 as p, discoverLinkedPullTargets as r, getEnvApiKey as s, COMMANDS as t, isFileGitDirty as u };
+export { resolveOAuthAccessToken as _, discoverOAuthLogin as a, createStatelyProjectConfig as b, formatPlanSummary as c, getEnvCredential as d, inferInitProjectName as f, resolveConfiguredPullTargets as g, resolveApiKey as h, discoverLinkedPullTargets as i, formatStoredCredentialSource as l, isFileGitDirty as m, buildOAuthLoginStart as n, discoverRemoteProjectMachineTargets as o, initProject as p, classifyPushCandidates as r, formatMissingNewMachineDirMessage as s, COMMANDS as t, getEnvApiKey as u, run$1 as v, scanProjectSources as y };

package/dist/index.d.mts

@@ -1,8 +1,26 @@
 import { Command } from "@oclif/core";
-import { ConnectedRepo, CreateProjectInput, ProjectData, StudioClient } from "@statelyai/sdk";
+import { ConnectedRepo, CreateProjectInput, OAuthAuthorizationServerMetadata, OAuthProtectedResourceMetadata, ProjectData, StudioClient } from "@statelyai/sdk";
 import { SyncPlan } from "@statelyai/sdk/sync";
 import * as _oclif_core_interfaces0 from "@oclif/core/interfaces";
 
+//#region src/credentials.d.ts
+type StatelyCredential = {
+  type: 'api_key';
+  token: string;
+} | {
+  type: 'oauth';
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+};
+type CredentialBackend = 'file' | 'linux-secret-tool' | 'macos-keychain';
+type StoredCredential = {
+  credential?: StatelyCredential;
+  authMode?: 'none';
+  backend: CredentialBackend;
+  location: string;
+};
+//#endregion
 //#region src/projectConfig.d.ts
 interface StatelySourceConfig {
   include: string[];
@@ -90,10 +108,42 @@ type ApiKeyResolution = {
 };
 declare function getEnvApiKey(): {
   apiKey: string;
-  variable: 'NEXT_PUBLIC_STATELY_API_KEY' | 'STATELY_API_KEY';
+  variable: 'NEXT_PUBLIC_STATELY_API_KEY' | 'STATELY_API_KEY' | 'STATELY_ACCESS_TOKEN';
+} | undefined;
+declare function getEnvCredential(): {
+  credential: StatelyCredential;
+  variable: 'NEXT_PUBLIC_STATELY_API_KEY' | 'STATELY_API_KEY' | 'STATELY_ACCESS_TOKEN';
 } | undefined;
 declare function resolveApiKey(explicitApiKey?: string): Promise<ApiKeyResolution>;
+declare function resolveOAuthAccessToken(): Promise<ApiKeyResolution>;
+interface OAuthLoginDiscovery {
+  authorizationServer: OAuthAuthorizationServerMetadata;
+  authorizationEndpoint: string;
+  clientId: string;
+  protectedResource?: OAuthProtectedResourceMetadata;
+  resourceUrl: string;
+  scopes: string[];
+  tokenEndpoint: string;
+}
+declare function discoverOAuthLogin(options?: {
+  baseUrl?: string;
+  clientId?: string;
+  fetch?: typeof fetch;
+  redirectUri?: string;
+}): Promise<OAuthLoginDiscovery>;
 declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string;
+declare function buildOAuthLoginStart(options: {
+  baseUrl?: string;
+  clientId?: string;
+  fetch?: typeof fetch;
+  redirectUri: string;
+  state: string;
+}): Promise<{
+  authorizeUrl: string;
+  codeVerifier: string;
+  discovery: OAuthLoginDiscovery;
+}>;
+declare function formatStoredCredentialSource(storedCredential: StoredCredential): string;
 declare function formatMissingNewMachineDirMessage(options: {
   config: Pick<StatelyProjectConfig, 'include' | 'newMachinesDir'>;
   remoteMachineCount: number;
@@ -230,7 +280,9 @@ declare class LoginCommand extends Command {
   static flags: {
     help: _oclif_core_interfaces0.BooleanFlag<void>;
     'api-key': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
     stdin: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    auth: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }
@@ -265,4 +317,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: any, entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, PushCandidateClassification, RemoteProjectMachineTarget, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, run, scanProjectSources };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, OAuthLoginDiscovery, PushCandidateClassification, RemoteProjectMachineTarget, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveOAuthAccessToken, run, scanProjectSources };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as formatMissingNewMachineDirMessage, c as inferInitProjectName, d as resolveApiKey, f as resolveConfiguredPullTargets, h as createStatelyProjectConfig, i as discoverRemoteProjectMachineTargets, l as initProject, m as scanProjectSources, n as classifyPushCandidates, o as formatPlanSummary, p as run, r as discoverLinkedPullTargets, s as getEnvApiKey, t as COMMANDS, u as isFileGitDirty } from "./cli-DB0A-O4Y.mjs";
+import { _ as resolveOAuthAccessToken, a as discoverOAuthLogin, b as createStatelyProjectConfig, c as formatPlanSummary, d as getEnvCredential, f as inferInitProjectName, g as resolveConfiguredPullTargets, h as resolveApiKey, i as discoverLinkedPullTargets, l as formatStoredCredentialSource, m as isFileGitDirty, n as buildOAuthLoginStart, o as discoverRemoteProjectMachineTargets, p as initProject, r as classifyPushCandidates, s as formatMissingNewMachineDirMessage, t as COMMANDS, u as getEnvApiKey, v as run, y as scanProjectSources } from "./cli-jiby9qdf.mjs";
 
-export { COMMANDS, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, run, scanProjectSources };
+export { COMMANDS, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveOAuthAccessToken, run, scanProjectSources };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statelyai",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Command-line tools for Stately",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",
-    "@statelyai/sdk": "0.11.0"
+    "@statelyai/sdk": "0.12.1"
   },
   "devDependencies": {
     "tsdown": "0.21.0-beta.2",