@statelyai/sdk 0.4.1 → 0.5.1

package/dist/cli.mjs

@@ -1,8 +1,651 @@
 #!/usr/bin/env node
 import { planSync, pullSync } from "./sync.mjs";
+import fs from "node:fs/promises";
+import * as path$1 from "node:path";
 import path from "node:path";
+import fs$1, { watch } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Args, Command, Flags, flush, handle, run as run$1 } from "@oclif/core";
+import * as crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import * as http from "node:http";
 
+//#region src/cliHost.ts
+const DEFAULT_SYNC_MAX_FILES = 150;
+const DEFAULT_SYNC_MAX_BYTES = 2e6;
+const supportedDocumentPattern = /\.(?:c|m)?(?:jsx?|tsx?)$|\.jsonc?$|\.ya?ml$|\.mmd$|\.mermaid$/i;
+var WebSocketClient = class {
+	buffer = Buffer.alloc(0);
+	listeners = /* @__PURE__ */ new Set();
+	constructor(socket) {
+		this.socket = socket;
+		socket.on("data", (chunk) => {
+			const nextChunk = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+			this.buffer = Buffer.concat([this.buffer, nextChunk]);
+			this.readFrames();
+		});
+	}
+	onMessage(listener) {
+		this.listeners.add(listener);
+	}
+	send(message) {
+		this.socket.write(encodeWebSocketFrame(JSON.stringify(message)));
+	}
+	close() {
+		this.socket.end();
+	}
+	readFrames() {
+		while (this.buffer.length >= 2) {
+			const first = this.buffer[0];
+			const second = this.buffer[1];
+			const opcode = first & 15;
+			const masked = (second & 128) !== 0;
+			let length = second & 127;
+			let offset = 2;
+			if (length === 126) {
+				if (this.buffer.length < offset + 2) return;
+				length = this.buffer.readUInt16BE(offset);
+				offset += 2;
+			} else if (length === 127) {
+				if (this.buffer.length < offset + 8) return;
+				const bigLength = this.buffer.readBigUInt64BE(offset);
+				if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+					this.socket.destroy(/* @__PURE__ */ new Error("WebSocket frame is too large."));
+					return;
+				}
+				length = Number(bigLength);
+				offset += 8;
+			}
+			const maskLength = masked ? 4 : 0;
+			if (this.buffer.length < offset + maskLength + length) return;
+			const mask = masked ? this.buffer.subarray(offset, offset + 4) : void 0;
+			offset += maskLength;
+			const payload = Buffer.from(this.buffer.subarray(offset, offset + length));
+			this.buffer = this.buffer.subarray(offset + length);
+			if (mask) for (let index = 0; index < payload.length; index++) payload[index] = payload[index] ^ mask[index % 4];
+			if (opcode === 8) {
+				this.close();
+				return;
+			}
+			if (opcode === 9) {
+				this.socket.write(encodeWebSocketFrame(payload, 10));
+				continue;
+			}
+			if (opcode !== 1) continue;
+			const message = JSON.parse(payload.toString("utf8"));
+			for (const listener of this.listeners) listener(message);
+		}
+	}
+};
+var RemoteEditorSession = class {
+	currentGraph;
+	lastPersistedGraph;
+	currentSourceLocations;
+	currentFormat;
+	ready = false;
+	pendingMessages = [];
+	pendingRetrievals = /* @__PURE__ */ new Map();
+	retrieveRequestCount = 0;
+	watchedSourceUris = /* @__PURE__ */ new Set();
+	selfEditCount = 0;
+	watcher;
+	constructor(options, sendMessage) {
+		this.options = options;
+		this.sendMessage = sendMessage;
+		this.watcher = watchWorkspace(this.options.rootDir, (uri) => {
+			this.handleSavedDocument(uri);
+		});
+	}
+	dispose() {
+		for (const pending of this.pendingRetrievals.values()) pending.reject(/* @__PURE__ */ new Error("Editor session disposed before export completed."));
+		this.pendingRetrievals.clear();
+		this.watcher?.dispose();
+	}
+	async receiveMessage(msg) {
+		this.log("recv", msg.type, msg);
+		switch (msg.type) {
+			case "@statelyai.ready":
+				await this.initializeEditor();
+				break;
+			case "@statelyai.loaded":
+				this.currentGraph = msg.graph;
+				this.lastPersistedGraph = msg.graph;
+				this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+				this.updateSourceLocations(this.currentSourceLocations);
+				break;
+			case "@statelyai.change":
+				this.currentGraph = msg.graph;
+				this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+				this.updateSourceLocations(this.currentSourceLocations);
+				break;
+			case "@statelyai.save":
+				await this.saveFromEditor(msg);
+				break;
+			case "@statelyai.retrieved":
+				this.resolveRetrievedSource(msg);
+				break;
+			case "@statelyai.clipboardRead":
+				this.postMessage({
+					type: "@statelyai.clipboardReadResponse",
+					requestId: msg.requestId,
+					text: ""
+				});
+				break;
+			case "@statelyai.error":
+				this.handleErrorMessage(msg);
+				break;
+		}
+	}
+	async initializeEditor() {
+		this.ready = true;
+		try {
+			const update = await this.parseRootDocument();
+			this.currentFormat = update.format;
+			this.currentSourceLocations = update.sourceLocations;
+			this.updateSourceLocations(update.sourceLocations);
+			this.postMessage({
+				type: "@statelyai.init",
+				machine: update.machine,
+				format: update.format,
+				sourceLocations: update.sourceLocations,
+				mode: "editing",
+				theme: "light",
+				unsavedIndicator: { enabled: true },
+				leftPanels: [],
+				rightPanels: [],
+				activePanels: []
+			});
+		} catch (error) {
+			this.showError(formatError(error, "Failed to initialize the visual editor."));
+			return;
+		}
+		for (const pending of this.pendingMessages) this.sendMessage(pending);
+		this.pendingMessages = [];
+	}
+	async handleSavedDocument(uri) {
+		if (uri !== this.options.rootUri && !this.watchedSourceUris.has(uri)) return;
+		if (this.selfEditCount > 0) return;
+		try {
+			const update = await this.parseRootDocument();
+			this.currentFormat = update.format;
+			this.currentSourceLocations = update.sourceLocations;
+			this.updateSourceLocations(update.sourceLocations);
+			this.postMessage({
+				type: "@statelyai.update",
+				machine: update.machine,
+				format: update.format,
+				sourceLocations: update.sourceLocations
+			});
+		} catch (error) {
+			this.showError(formatError(error, "Failed to read the saved document."));
+		}
+	}
+	async saveFromEditor(msg) {
+		const validationErrors = getValidationErrors(msg.validations);
+		if (validationErrors.length > 0) {
+			const message = formatValidationErrorMessage(validationErrors);
+			this.postMessage({
+				type: "@statelyai.toast",
+				message,
+				toastType: "error"
+			});
+			this.showError(message);
+			return;
+		}
+		this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+		this.updateSourceLocations(this.currentSourceLocations);
+		try {
+			const serialized = await this.getSerializedPayloadForCurrentFormat();
+			const documents = await collectSourceDocuments({
+				rootFileName: this.options.fileName,
+				rootDir: this.options.rootDir,
+				extraUris: sourceLocationUris(this.currentSourceLocations)
+			});
+			const response = await this.postSync("/api/editor-sync/apply", {
+				rootUri: this.options.rootUri,
+				rootFileName: this.options.fileName,
+				rootDir: this.options.rootDir,
+				documents,
+				machineConfig: msg.machineConfig,
+				patches: msg.patches,
+				prevGraph: this.lastPersistedGraph ?? this.currentGraph,
+				nextGraph: msg.graph,
+				sourceLocations: this.currentSourceLocations,
+				serialized
+			});
+			if (response.replacements.length === 0) {
+				const message = "Unable to apply Viz changes to the source file automatically.";
+				this.postMessage({
+					type: "@statelyai.toast",
+					message,
+					toastType: "error"
+				});
+				this.showError(message);
+				return;
+			}
+			await this.runWithSelfEdit(async () => {
+				await applyFileReplacements(response.replacements, this.options.rootUri);
+			});
+			this.currentGraph = msg.graph;
+			this.lastPersistedGraph = msg.graph;
+		} catch (error) {
+			const message = formatError(error, "Failed to apply Viz changes.");
+			this.postMessage({
+				type: "@statelyai.toast",
+				message,
+				toastType: "error"
+			});
+			this.showError(message);
+		}
+	}
+	async parseRootDocument() {
+		const documents = await collectSourceDocuments({
+			rootFileName: this.options.fileName,
+			rootDir: this.options.rootDir,
+			extraUris: sourceLocationUris(this.currentSourceLocations)
+		});
+		return this.postSync("/api/editor-sync/parse", {
+			rootUri: this.options.rootUri,
+			rootFileName: this.options.fileName,
+			rootDir: this.options.rootDir,
+			documents
+		});
+	}
+	async postSync(pathname, body) {
+		const url = new URL(pathname, normalizedBaseUrl(this.options.editorUrl));
+		const headers = { "Content-Type": "application/json" };
+		if (this.options.apiKey) headers.Authorization = `Bearer ${this.options.apiKey}`;
+		const response = await fetch(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		});
+		const data = await response.json().catch(() => null);
+		if (!response.ok) {
+			const message = data && typeof data === "object" && "error" in data && typeof data.error === "string" ? data.error : `HTTP ${response.status}`;
+			throw new Error(message);
+		}
+		return data;
+	}
+	async getSerializedPayloadForCurrentFormat() {
+		const format = this.currentFormat;
+		if (!format || format === "xstate") return;
+		try {
+			const serialized = await this.requestSerialized(format);
+			return { [format]: serialized };
+		} catch {
+			return;
+		}
+	}
+	requestSerialized(format) {
+		const requestId = `retrieve-${++this.retrieveRequestCount}`;
+		return new Promise((resolve, reject) => {
+			this.pendingRetrievals.set(requestId, {
+				resolve,
+				reject
+			});
+			this.postMessage({
+				type: "@statelyai.retrieve",
+				requestId,
+				format
+			});
+		});
+	}
+	resolveRetrievedSource(msg) {
+		const pending = this.pendingRetrievals.get(msg.requestId);
+		if (!pending) return;
+		this.pendingRetrievals.delete(msg.requestId);
+		const serialized = typeof msg.data === "string" ? msg.data : JSON.stringify(msg.data, null, 2);
+		pending.resolve(serialized);
+	}
+	handleErrorMessage(msg) {
+		if (msg.requestId) {
+			const pending = this.pendingRetrievals.get(msg.requestId);
+			if (pending) {
+				this.pendingRetrievals.delete(msg.requestId);
+				pending.reject(new Error(msg.message));
+				return;
+			}
+		}
+		this.showError(msg.message);
+	}
+	updateSourceLocations(sourceLocations) {
+		this.watchedSourceUris.clear();
+		for (const location of sourceLocations?.states ?? []) if (location.uri !== this.options.rootUri) this.watchedSourceUris.add(location.uri);
+	}
+	async runWithSelfEdit(operation) {
+		this.selfEditCount++;
+		try {
+			return await operation();
+		} finally {
+			this.selfEditCount--;
+		}
+	}
+	postMessage(msg) {
+		this.log("send", msg.type, msg);
+		if (!this.ready) {
+			this.pendingMessages.push(msg);
+			return;
+		}
+		this.sendMessage(msg);
+	}
+	showError(message) {
+		console.error(`Stately Editor: ${message}`);
+	}
+	log(direction, type, payload) {
+		if (this.options.debug) console.error(`[${direction}] ${type}`, payload ?? "");
+	}
+};
+async function openEditor(options) {
+	const fileName = path$1.resolve(options.fileName);
+	await fs.access(fileName);
+	const rootUri = fileNameToUri(fileName);
+	const rootDir = path$1.dirname(fileName);
+	let activeClient;
+	let session;
+	const server = http.createServer((request, response) => {
+		if (new URL(request.url ?? "/", `http://${request.headers.host}`).pathname !== "/") {
+			response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+			response.end("Not found");
+			return;
+		}
+		response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		response.end(getCliWebviewContent({
+			editorUrl: options.editorUrl,
+			apiKey: options.apiKey
+		}));
+	});
+	server.on("upgrade", (request, socket) => {
+		if (request.url !== "/ws") {
+			socket.end("HTTP/1.1 404 Not Found\r\n\r\n");
+			return;
+		}
+		const key = request.headers["sec-websocket-key"];
+		if (typeof key !== "string") {
+			socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+			return;
+		}
+		const accept = crypto.createHash("sha1").update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest("base64");
+		socket.write([
+			"HTTP/1.1 101 Switching Protocols",
+			"Upgrade: websocket",
+			"Connection: Upgrade",
+			`Sec-WebSocket-Accept: ${accept}`,
+			"\r\n"
+		].join("\r\n"));
+		activeClient?.close();
+		session?.dispose();
+		activeClient = new WebSocketClient(socket);
+		session = new RemoteEditorSession({
+			...options,
+			fileName,
+			rootUri,
+			rootDir
+		}, (message) => activeClient?.send(message));
+		activeClient.onMessage((message) => {
+			session?.receiveMessage(message);
+		});
+	});
+	await listen(server, options.port, options.host);
+	const address = server.address();
+	const port = typeof address === "object" && address ? address.port : options.port;
+	const editorPageUrl = `http://${options.host}:${port}`;
+	console.log(`Stately visual editor: ${editorPageUrl}`);
+	console.log(`Editing ${fileName}`);
+	if (options.shouldOpen) openBrowser(editorPageUrl);
+	const shutdown = () => {
+		session?.dispose();
+		activeClient?.close();
+		server.close();
+	};
+	process.once("SIGINT", () => {
+		shutdown();
+		process.exit(0);
+	});
+	process.once("SIGTERM", () => {
+		shutdown();
+		process.exit(0);
+	});
+}
+async function collectSourceDocuments(options) {
+	const files = new Set([options.rootFileName]);
+	const maxFiles = Number.parseInt(process.env.STATELY_SYNC_MAX_FILES ?? "", 10) || DEFAULT_SYNC_MAX_FILES;
+	const maxBytes = Number.parseInt(process.env.STATELY_SYNC_MAX_BYTES ?? "", 10) || DEFAULT_SYNC_MAX_BYTES;
+	for (const uri of options.extraUris ?? []) files.add(sourceUriToFileName(uri));
+	await collectDirectoryFiles(options.rootDir, files, maxFiles);
+	const documents = [];
+	let totalBytes = 0;
+	for (const fileName of files) {
+		if (!isSupportedDocument(fileName)) continue;
+		const text = await fs.readFile(fileName, "utf8").catch(() => null);
+		if (text === null) continue;
+		totalBytes += Buffer.byteLength(text);
+		if (totalBytes > maxBytes) throw new Error(`Source payload exceeds ${maxBytes} bytes.`);
+		documents.push({
+			uri: fileNameToUri(fileName),
+			fileName,
+			text
+		});
+	}
+	return documents;
+}
+async function collectDirectoryFiles(rootDir, files, maxFiles) {
+	const queue = [rootDir];
+	while (queue.length > 0 && files.size < maxFiles) {
+		const dir = queue.shift();
+		const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+		for (const entry of entries) {
+			if (files.size >= maxFiles) break;
+			if (entry.name.startsWith(".") || shouldSkipDirectory(entry.name)) continue;
+			const fileName = path$1.join(dir, entry.name);
+			if (entry.isDirectory()) queue.push(fileName);
+			else if (entry.isFile() && isSupportedDocument(fileName)) files.add(fileName);
+		}
+	}
+}
+function shouldSkipDirectory(name) {
+	return [
+		"node_modules",
+		"dist",
+		"out",
+		"build",
+		"coverage",
+		".git"
+	].includes(name);
+}
+function isSupportedDocument(fileName) {
+	return supportedDocumentPattern.test(fileName);
+}
+async function applyFileReplacements(replacements, defaultUri) {
+	const replacementsByUri = /* @__PURE__ */ new Map();
+	for (const replacement of replacements) {
+		const uri = replacement.uri ?? defaultUri;
+		const existing = replacementsByUri.get(uri) ?? [];
+		existing.push(replacement);
+		replacementsByUri.set(uri, existing);
+	}
+	for (const [uri, uriReplacements] of replacementsByUri) {
+		const fileName = sourceUriToFileName(uri);
+		const nextText = applyReplacementsToText(await fs.readFile(fileName, "utf8"), uriReplacements);
+		await fs.writeFile(fileName, nextText, "utf8");
+	}
+}
+function applyReplacementsToText(text, replacements) {
+	let updated = text;
+	const sorted = [...replacements].sort(compareReplacementRangesDescending);
+	for (const replacement of sorted) {
+		const lineStarts = getLineStarts(updated);
+		const start = offsetAt(lineStarts, replacement.range.startLine, replacement.range.startChar);
+		const end = offsetAt(lineStarts, replacement.range.endLine, replacement.range.endChar);
+		updated = `${updated.slice(0, start)}${replacement.newText}${updated.slice(end)}`;
+	}
+	return updated;
+}
+function watchWorkspace(rootDir, listener) {
+	let watcher;
+	const timers = /* @__PURE__ */ new Map();
+	const queue = (fileName) => {
+		const existing = timers.get(fileName);
+		if (existing) clearTimeout(existing);
+		timers.set(fileName, setTimeout(() => {
+			timers.delete(fileName);
+			listener(fileNameToUri(fileName));
+		}, 75));
+	};
+	try {
+		watcher = watch(rootDir, { recursive: true }, (_event, fileName) => {
+			if (fileName) queue(path$1.join(rootDir, fileName.toString()));
+		});
+	} catch {
+		watcher = watch(rootDir, (_event, fileName) => {
+			if (fileName) queue(path$1.join(rootDir, fileName.toString()));
+		});
+	}
+	return { dispose() {
+		watcher?.close();
+		for (const timer of timers.values()) clearTimeout(timer);
+		timers.clear();
+	} };
+}
+function getCliWebviewContent(options) {
+	const baseUrl = normalizedBaseUrl(options.editorUrl);
+	const url = new URL(`${baseUrl}/embed`);
+	if (options.apiKey) url.searchParams.set("api_key", options.apiKey);
+	return `<!DOCTYPE html>
+<html lang="en" style="height:100%;margin:0">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    body { margin: 0; padding: 0; height: 100vh; overflow: hidden; }
+    iframe { border: 0; width: 100%; height: 100%; display: block; }
+  </style>
+</head>
+<body>
+  <iframe
+    id="stately-editor"
+    src="${escapeAttribute(url.toString())}"
+    allow="clipboard-read; clipboard-write"
+  ></iframe>
+  <script>
+    const iframe = document.getElementById('stately-editor');
+    const socket = new WebSocket(
+      (location.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + location.host + '/ws'
+    );
+    const pending = [];
+
+    function sendToCli(message) {
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify(message));
+        return;
+      }
+      pending.push(message);
+    }
+
+    socket.addEventListener('open', () => {
+      while (pending.length > 0) {
+        socket.send(JSON.stringify(pending.shift()));
+      }
+    });
+
+    socket.addEventListener('message', (event) => {
+      iframe.contentWindow?.postMessage(JSON.parse(event.data), '*');
+    });
+
+    window.addEventListener('message', (event) => {
+      if (!event.data?.type?.startsWith?.('@statelyai.')) {
+        return;
+      }
+      sendToCli(event.data);
+    });
+  <\/script>
+</body>
+</html>`;
+}
+function encodeWebSocketFrame(payload, opcode = 1) {
+	const data = typeof payload === "string" ? Buffer.from(payload) : payload;
+	const headerLength = data.length < 126 ? 2 : data.length <= 65535 ? 4 : 10;
+	const frame = Buffer.alloc(headerLength + data.length);
+	frame[0] = 128 | opcode;
+	if (data.length < 126) {
+		frame[1] = data.length;
+		data.copy(frame, 2);
+	} else if (data.length <= 65535) {
+		frame[1] = 126;
+		frame.writeUInt16BE(data.length, 2);
+		data.copy(frame, 4);
+	} else {
+		frame[1] = 127;
+		frame.writeBigUInt64BE(BigInt(data.length), 2);
+		data.copy(frame, 10);
+	}
+	return frame;
+}
+function listen(server, port, host) {
+	return new Promise((resolve) => {
+		server.listen(port, host, resolve);
+	});
+}
+function openBrowser(url) {
+	spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open", process.platform === "win32" ? [
+		"/c",
+		"start",
+		"",
+		url
+	] : [url], {
+		detached: true,
+		stdio: "ignore"
+	}).unref();
+}
+function getValidationErrors(validations) {
+	return (validations ?? []).filter((validation) => validation.level === "error");
+}
+function formatValidationErrorMessage(errors) {
+	const [firstError] = errors;
+	if (!firstError) return "Cannot save Viz changes because the graph has validation errors.";
+	if (errors.length === 1) return `Cannot save Viz changes: ${firstError.message}`;
+	return `Cannot save Viz changes: ${errors.length} validation errors. First: ${firstError.message}`;
+}
+function sourceLocationUris(sourceLocations) {
+	return [
+		...sourceLocations?.root ? [sourceLocations.root.uri] : [],
+		...(sourceLocations?.states ?? []).map((state) => state.uri),
+		...(sourceLocations?.staticValues ?? []).map((value) => value.uri)
+	];
+}
+function fileNameToUri(fileName) {
+	return pathToFileURL(path$1.resolve(fileName)).toString();
+}
+function sourceUriToFileName(uriOrPath) {
+	if (uriOrPath.startsWith("file://")) return fileURLToPath(uriOrPath);
+	if (/^[a-z][a-z\d+.-]*:/i.test(uriOrPath)) throw new Error(`Unsupported non-file URI: ${uriOrPath}`);
+	return path$1.resolve(uriOrPath);
+}
+function getLineStarts(text) {
+	const lineStarts = [0];
+	for (let index = 0; index < text.length; index += 1) if (text.charCodeAt(index) === 10) lineStarts.push(index + 1);
+	return lineStarts;
+}
+function offsetAt(lineStarts, line, character) {
+	const lineStart = lineStarts[line];
+	if (lineStart === void 0) return lineStarts[lineStarts.length - 1] + character;
+	return lineStart + character;
+}
+function compareReplacementRangesDescending(left, right) {
+	if (left.range.startLine !== right.range.startLine) return right.range.startLine - left.range.startLine;
+	return right.range.startChar - left.range.startChar;
+}
+function normalizedBaseUrl(value) {
+	return value.replace(/\/+$/, "");
+}
+function formatError(error, fallback) {
+	return error instanceof Error ? error.message : fallback;
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+//#endregion
 //#region src/cli.ts
 function loadLocalEnv() {
 	if (typeof process.loadEnvFile !== "function") return;
@@ -12,20 +655,23 @@ function loadLocalEnv() {
 	} catch {}
 }
 loadLocalEnv();
+function getDefaultApiKey() {
+	return process.env.STATELY_API_KEY ?? process.env.NEXT_PUBLIC_STATELY_API_KEY;
+}
+function getDefaultBaseUrl() {
+	return process.env.STATELY_API_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? process.env.NEXT_PUBLIC_STATELY_API_URL;
+}
+function getDefaultEditorUrl() {
+	return process.env.STATELY_EDITOR_URL ?? process.env.NEXT_PUBLIC_BETA_EDITOR_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3001";
+}
 const sharedFlags = {
 	help: Flags.help({ char: "h" }),
 	"fail-on-changes": Flags.boolean({
 		default: false,
 		description: "Exit with a nonzero code when differences are found"
 	}),
-	"api-key": Flags.string({
-		description: "Stately API key used for remote source or target resolution",
-		default: process.env.STATELY_API_KEY ?? process.env.NEXT_PUBLIC_STATELY_API_KEY
-	}),
-	"base-url": Flags.string({
-		description: "Base URL for Stately Studio or a self-hosted deployment",
-		default: process.env.STATELY_API_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? process.env.NEXT_PUBLIC_STATELY_API_URL
-	})
+	"api-key": Flags.string({ description: "Stately API key used for remote source or target resolution" }),
+	"base-url": Flags.string({ description: "Base URL for Stately Studio or a self-hosted deployment" })
 };
 function formatChangeList(label, items) {
 	if (items.length === 0) return null;
@@ -82,8 +728,8 @@ var PlanCommand = class PlanCommand extends ParsedSyncCommand {
 		const plan = await planSync({
 			source: args.source,
 			target: args.target,
-			apiKey: flags["api-key"],
-			baseUrl: flags["base-url"]
+			apiKey: flags["api-key"] ?? getDefaultApiKey(),
+			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
 		});
 		this.log(formatPlanSummary(plan));
 		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
@@ -98,8 +744,8 @@ var DiffCommand = class DiffCommand extends ParsedSyncCommand {
 		const plan = await planSync({
 			source: args.source,
 			target: args.target,
-			apiKey: flags["api-key"],
-			baseUrl: flags["base-url"]
+			apiKey: flags["api-key"] ?? getDefaultApiKey(),
+			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
 		});
 		this.log(formatPlanSummary(plan));
 		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
@@ -114,27 +760,82 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 		const result = await pullSync({
 			source: args.source,
 			target: args.target,
-			apiKey: flags["api-key"],
-			baseUrl: flags["base-url"]
+			apiKey: flags["api-key"] ?? getDefaultApiKey(),
+			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
 		});
 		this.log(`Pulled: ${result.source.locator} -> ${result.outputPath}\nTarget: ${result.target.kind} (${result.target.format})`);
 	}
 };
+var OpenCommand = class OpenCommand extends Command {
+	static enableJsonFlag = false;
+	static summary = "Open a local file in the Stately visual editor.";
+	static description = "Starts a local browser-backed editor session. Saved file changes update the visual editor, and saved visual edits are written back to the source file.";
+	static args = { file: Args.string({
+		required: true,
+		description: "Local source file to edit visually."
+	}) };
+	static flags = {
+		help: Flags.help({ char: "h" }),
+		"api-key": Flags.string({ description: "Stately API key used when the editor server requires auth" }),
+		"editor-url": Flags.string({ description: "Base URL for the Stately editor embed" }),
+		host: Flags.string({
+			description: "Local server host",
+			default: "127.0.0.1"
+		}),
+		port: Flags.integer({
+			description: "Local server port. Defaults to a random available port.",
+			default: 0,
+			min: 0
+		}),
+		open: Flags.boolean({
+			description: "Open the local editor URL in the default browser",
+			default: true,
+			allowNo: true
+		}),
+		debug: Flags.boolean({
+			description: "Log editor protocol messages",
+			default: false
+		})
+	};
+	async run() {
+		const { args, flags } = await this.parse(OpenCommand);
+		await openEditor({
+			fileName: path.resolve(args.file),
+			editorUrl: flags["editor-url"] ?? getDefaultEditorUrl(),
+			host: flags.host,
+			port: flags.port,
+			shouldOpen: flags.open,
+			apiKey: flags["api-key"] ?? getDefaultApiKey(),
+			debug: flags.debug
+		});
+	}
+};
 const COMMANDS = {
 	plan: PlanCommand,
 	diff: DiffCommand,
-	pull: PullCommand
+	pull: PullCommand,
+	open: OpenCommand
 };
-async function run(argv = process.argv.slice(2)) {
+async function run(argv = process.argv.slice(2), entryUrl = import.meta.url) {
 	const normalizedArgv = argv.length === 1 && argv[0] === "-h" ? ["--help"] : argv;
 	try {
-		await run$1(normalizedArgv, import.meta.url);
+		await run$1(normalizedArgv, entryUrl);
 		await flush();
 	} catch (error) {
 		await handle(error);
 	}
 }
-if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) run();
+function isDirectExecution() {
+	const entryPath = process.argv[1];
+	if (!entryPath) return false;
+	const modulePath = fileURLToPath(import.meta.url);
+	try {
+		return fs$1.realpathSync(entryPath) === fs$1.realpathSync(modulePath);
+	} catch {
+		return path.resolve(entryPath) === modulePath;
+	}
+}
+if (isDirectExecution()) run();
 
 //#endregion
 export { COMMANDS, formatPlanSummary, run };