@statelyai/sdk 0.1.1 → 0.3.0

package/dist/sync-CzEOizjx.mjs

@@ -0,0 +1,558 @@
+import { createStatelyClient } from "./studio.mjs";
+import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
+import { getDiff, isEmptyDiff } from "@statelyai/graph";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+//#region src/serializeJS.ts
+const VALID_IDENT = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+var RawCode = class {
+	constructor(code) {
+		this.code = code;
+	}
+};
+function raw(code) {
+	return new RawCode(code);
+}
+function serializeJS(value, indent = 0, step = 2) {
+	if (value instanceof RawCode) return value.code;
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "string") return `'${escapeString(value)}'`;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return serializeArray(value, indent, step);
+	if (typeof value === "object") return serializeObject(value, indent, step);
+	return String(value);
+}
+function escapeString(value) {
+	return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+function serializeArray(array, indent, step) {
+	const values = array.filter((item) => item !== void 0);
+	if (values.length === 0) return "[]";
+	const innerIndent = indent + step;
+	const pad = " ".repeat(innerIndent);
+	const closePad = " ".repeat(indent);
+	return `[\n${values.map((item) => `${pad}${serializeJS(item, innerIndent, step)}`).join(",\n")},\n${closePad}]`;
+}
+function serializeObject(object, indent, step) {
+	const entries = Object.entries(object).filter(([, value]) => value !== void 0);
+	if (entries.length === 0) return "{}";
+	const innerIndent = indent + step;
+	const pad = " ".repeat(innerIndent);
+	const closePad = " ".repeat(indent);
+	return `{\n${entries.map(([key, value]) => {
+		const serializedKey = VALID_IDENT.test(key) ? key : `'${escapeString(key)}'`;
+		const serializedValue = serializeJS(value, innerIndent, step);
+		if (value instanceof RawCode && serializedValue.includes("\n")) return `${pad}${serializedKey}: ${indentRawCode(serializedValue, innerIndent)}`;
+		return `${pad}${serializedKey}: ${serializedValue}`;
+	}).join(",\n")},\n${closePad}}`;
+}
+function indentRawCode(code, indent) {
+	const lines = code.split("\n");
+	if (lines.length <= 1) return code;
+	const pad = " ".repeat(indent);
+	return [lines[0], ...lines.slice(1).map((line) => line.trim() === "" ? "" : `${pad}${line}`)].join("\n");
+}
+
+//#endregion
+//#region src/graphToMachineConfig.ts
+function singleOrArray(items) {
+	return items.length === 1 ? items[0] : items;
+}
+function singleOrArrayRecord(record) {
+	const next = {};
+	for (const [key, value] of Object.entries(record)) next[key] = singleOrArray(value);
+	return next;
+}
+function simplifyAttributes(value) {
+	for (const key of Object.keys(value)) {
+		const item = value[key];
+		if (item === void 0 || item === null) {
+			delete value[key];
+			continue;
+		}
+		if (Array.isArray(item)) {
+			if (item.length === 0) delete value[key];
+			else if (item.length === 1) value[key] = item[0];
+			continue;
+		}
+		if (typeof item === "object" && Object.keys(item).length === 0) {
+			delete value[key];
+			continue;
+		}
+		if (typeof item === "string" && item === "") delete value[key];
+	}
+	return value;
+}
+function deepSimplify(config) {
+	for (const mapKey of ["on", "after"]) {
+		const value = config[mapKey];
+		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+		for (const transition of Object.values(value)) if (transition && typeof transition === "object" && !Array.isArray(transition)) simplifyAttributes(transition);
+		else if (Array.isArray(transition)) {
+			for (const item of transition) if (item && typeof item === "object") simplifyAttributes(item);
+		}
+	}
+	if (config.always && typeof config.always === "object") if (Array.isArray(config.always)) {
+		for (const item of config.always) if (item && typeof item === "object") simplifyAttributes(item);
+	} else simplifyAttributes(config.always);
+	simplifyAttributes(config);
+	if (config.states && typeof config.states === "object") for (const state of Object.values(config.states)) deepSimplify(state);
+	return config;
+}
+function serializeActionItem(action) {
+	const { type, params } = action;
+	switch (type) {
+		case "xstate.raise": return raw(`raise(${serializeJSValue(params?.event ?? { type: "unknown" })})`);
+		case "xstate.sendTo": return raw(`sendTo(${serializeJSValue(params?.to ?? "unknown")}, ${serializeJSValue(params?.event ?? { type: "unknown" })})`);
+		case "xstate.cancel": return raw(`cancel(${serializeJSValue(params?.sendId ?? "unknown")})`);
+		case "xstate.log": return raw(`log(${serializeJSValue(params?.label ?? "")})`);
+		default:
+			if (!params || Object.keys(params).length === 0) return { type };
+			return {
+				type,
+				params
+			};
+	}
+}
+function serializeJSValue(value) {
+	if (typeof value === "string") return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+	if (value && typeof value === "object") return rawObject(value);
+	return String(value);
+}
+function rawObject(value) {
+	return `{ ${Object.entries(value).map(([key, item]) => `${key}: ${serializeJSValue(item)}`).join(", ")} }`;
+}
+function graphToMachineConfig(graph, options = {}) {
+	const { showDescriptions = true } = options;
+	function getNodeConfig(nodeId) {
+		const node = graph.nodes.find((candidate) => candidate.id === nodeId);
+		if (!node) throw new Error(`Node not found: ${nodeId}`);
+		const config = {};
+		const initialNode = node.data.initialId ? graph.nodes.find((candidate) => candidate.id === node.data.initialId) : null;
+		Object.assign(config, {
+			id: node.parentId == null ? graph.id : node.id.endsWith(`.${node.data.key}`) ? void 0 : node.id,
+			...node.data.type ? { type: node.data.type } : {},
+			...initialNode ? { initial: initialNode.data.key } : {},
+			...node.data.entry?.length ? { entry: node.data.entry.map(serializeActionItem) } : {},
+			...node.data.exit?.length ? { exit: node.data.exit.map(serializeActionItem) } : {},
+			...node.data.invokes?.length ? { invoke: node.data.invokes.map((invoke) => ({
+				src: invoke.src,
+				id: invoke.id,
+				...invoke.input ? { input: invoke.input } : {}
+			})) } : {},
+			...node.data.tags?.length ? { tags: node.data.tags } : {},
+			...showDescriptions && node.data.description ? { description: node.data.description } : {},
+			...node.data.history ? { history: node.data.history } : {}
+		});
+		const childNodes = graph.nodes.filter((candidate) => candidate.parentId === node.id);
+		const edges = graph.edges.filter((edge) => edge.sourceId === node.id);
+		if (edges.length > 0) {
+			const on = {};
+			const after = {};
+			const always = [];
+			for (const edge of edges) {
+				const targetNode = graph.nodes.find((candidate) => candidate.id === edge.targetId);
+				const target = targetNode && targetNode.parentId === node.parentId ? targetNode.data.key : targetNode ? `#${targetNode.id}` : void 0;
+				const transition = {
+					...target ? { target } : {},
+					...edge.data.transitionType === "reenter" ? { reenter: true } : {},
+					...edge.data.guard ? { guard: edge.data.guard } : {},
+					...edge.data.actions?.length ? { actions: edge.data.actions.map(serializeActionItem) } : {},
+					...edge.data.description ? { description: edge.data.description } : {}
+				};
+				if (edge.data.eventType === "") {
+					always.push(transition);
+					continue;
+				}
+				if (edge.data.eventType.startsWith("xstate.after.")) {
+					const delay = edge.data.eventType.slice(13).split(".")[0];
+					after[delay] ??= [];
+					after[delay].push(transition);
+					continue;
+				}
+				on[edge.data.eventType] ??= [];
+				on[edge.data.eventType].push(transition);
+			}
+			if (Object.keys(on).length > 0) config.on = singleOrArrayRecord(on);
+			if (Object.keys(after).length > 0) config.after = singleOrArrayRecord(after);
+			if (always.length > 0) config.always = singleOrArray(always);
+		}
+		if (childNodes.length > 0) config.states = Object.fromEntries(childNodes.map((child) => [child.data.key, getNodeConfig(child.id)]));
+		return config;
+	}
+	const rootNode = graph.nodes.find((candidate) => candidate.parentId == null);
+	if (!rootNode) throw new Error("No root node found");
+	return deepSimplify(getNodeConfig(rootNode.id));
+}
+
+//#endregion
+//#region src/jsonSchemaToTSType.ts
+function jsonSchemaToTSType(schema) {
+	if (!schema) return "unknown";
+	if ("const" in schema) {
+		const value = schema.const;
+		return typeof value === "string" ? `'${value}'` : String(value);
+	}
+	if (schema.type === "array") return `Array<${jsonSchemaToTSType(schema.items)}>`;
+	if (schema.type === "object") {
+		const props = schema.properties;
+		if (!props || Object.keys(props).length === 0) return "Record<string, unknown>";
+		return `{ ${Object.entries(props).map(([key, value]) => `${key}: ${jsonSchemaToTSType(value)}`).join("; ")} }`;
+	}
+	switch (schema.type) {
+		case "string": return "string";
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "null": return "null";
+		default: return "unknown";
+	}
+}
+function contextSchemaToTSType(context) {
+	if (!context || Object.keys(context).length === 0) return null;
+	return `{ ${Object.entries(context).map(([key, schema]) => `${key}: ${jsonSchemaToTSType(schema)}`).join("; ")} }`;
+}
+function eventsSchemaToTSType(events) {
+	if (!events || Object.keys(events).length === 0) return null;
+	return Object.entries(events).map(([eventType, schema]) => {
+		const props = schema.properties;
+		const extraProps = Object.entries(props ?? {}).filter(([key]) => key !== "type").map(([key, value]) => `${key}?: ${jsonSchemaToTSType(value)}`);
+		if (extraProps.length === 0) return `{ type: '${eventType}' }`;
+		return `{ type: '${eventType}'; ${extraProps.join("; ")} }`;
+	}).join("\n  | ");
+}
+
+//#endregion
+//#region src/graphToXStateTS.ts
+const BUILTIN_ACTION_IMPORTS = {
+	"xstate.raise": "raise",
+	"xstate.sendTo": "sendTo",
+	"xstate.cancel": "cancel",
+	"xstate.log": "log"
+};
+function graphToXStateTS(graph, options = {}) {
+	const { exportStyle = "named" } = options;
+	const schemas = graph.data.schemas;
+	const impls = graph.data.implementations;
+	const hasSchemas = Boolean(schemas && (schemas.context || schemas.events || schemas.input || schemas.output));
+	const hasActions = Boolean(impls?.actions.length);
+	const hasGuards = Boolean(impls?.guards.length);
+	const hasActors = Boolean(impls?.actors.length);
+	const hasDelays = Boolean(impls?.delays.length);
+	const hasSetup = hasSchemas || hasActions || hasGuards || hasActors || hasDelays;
+	const imports = new Set([hasSetup ? "setup" : "createMachine"]);
+	for (const node of graph.nodes) for (const action of [...node.data.entry ?? [], ...node.data.exit ?? []]) {
+		const builtInImport = BUILTIN_ACTION_IMPORTS[action.type];
+		if (builtInImport) imports.add(builtInImport);
+	}
+	for (const edge of graph.edges) for (const action of edge.data.actions ?? []) {
+		const builtInImport = BUILTIN_ACTION_IMPORTS[action.type];
+		if (builtInImport) imports.add(builtInImport);
+	}
+	const machineConfig = graphToMachineConfig(graph);
+	if (hasActors) imports.add("fromPromise");
+	const machineExpr = hasSetup ? `setup(${serializeJS(buildSetupObject(graph), 0)}).createMachine(${serializeJS(machineConfig, 0)})` : `createMachine(${serializeJS(machineConfig, 0)})`;
+	const lines = [
+		`import { ${Array.from(imports).join(", ")} } from 'xstate';`,
+		"",
+		`const machine = ${machineExpr};`
+	];
+	if (exportStyle === "named") lines.push("", "export { machine };");
+	else if (exportStyle === "default") lines.push("", "export default machine;");
+	return `${lines.join("\n")}\n`;
+}
+function buildSetupObject(graph) {
+	const setup = {};
+	const schemas = graph.data.schemas;
+	const impls = graph.data.implementations;
+	const types = buildTypesBlock(schemas);
+	if (types) setup.types = types;
+	if (impls?.actions.length) setup.actions = buildActionsBlock(impls.actions);
+	if (impls?.guards.length) setup.guards = buildGuardsBlock(impls.guards);
+	if (impls?.actors.length) setup.actors = buildActorsBlock(impls.actors);
+	if (impls?.delays.length) setup.delays = buildDelaysBlock(impls.delays);
+	return setup;
+}
+function buildTypesBlock(schemas) {
+	if (!schemas) return;
+	const types = {};
+	const contextType = contextSchemaToTSType(schemas.context);
+	if (contextType) types.context = raw(`{} as ${contextType}`);
+	const eventsType = eventsSchemaToTSType(schemas.events);
+	if (eventsType) types.events = raw(`{} as\n    | ${eventsType}`);
+	if (schemas.input) types.input = raw(`{} as ${jsonSchemaToTSType(schemas.input)}`);
+	if (schemas.output) types.output = raw(`{} as ${jsonSchemaToTSType(schemas.output)}`);
+	return Object.keys(types).length > 0 ? types : void 0;
+}
+function buildActionsBlock(actions) {
+	return Object.fromEntries(actions.map((action) => [action.name, (() => {
+		const paramsType = action.paramsSchema ? `: ${jsonSchemaToTSType(action.paramsSchema)}` : "";
+		return raw(action.code?.body ? `function ({ context, event }, params${paramsType}) {\n  ${action.code.body}\n}` : `function ({ context, event }) {\n  // TODO: implement ${action.name}\n}`);
+	})()]));
+}
+function buildGuardsBlock(guards) {
+	return Object.fromEntries(guards.map((guard) => [guard.name, (() => {
+		const paramsType = guard.paramsSchema ? `: ${jsonSchemaToTSType(guard.paramsSchema)}` : "";
+		return raw(guard.code?.body ? `function ({ context, event }, params${paramsType}) {\n  ${guard.code.body}\n}` : `function ({ context, event }) {\n  // TODO: implement ${guard.name}\n  return false;\n}`);
+	})()]));
+}
+function buildActorsBlock(actors) {
+	return Object.fromEntries(actors.map((actor) => [actor.name, (() => {
+		const inputType = actor.inputSchema ? `: { input: ${jsonSchemaToTSType(actor.inputSchema)} }` : "";
+		return raw(actor.code?.body ? `fromPromise(async ({ input }${inputType}) => {\n  ${actor.code.body}\n})` : `fromPromise(async ({ input }) => {\n  // TODO: implement ${actor.name}\n})`);
+	})()]));
+}
+function buildDelaysBlock(delays) {
+	return Object.fromEntries(delays.map((delay) => [delay.name, raw(delay.code?.body ? `function ({ context, event }) {\n  ${delay.code.body}\n}` : `function () {\n  // TODO: implement ${delay.name}\n  return 1000;\n}`)]));
+}
+
+//#endregion
+//#region src/sync.ts
+function isUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+async function fileExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function normalizeActions(value) {
+	if (value == null) return [];
+	return (Array.isArray(value) ? value : [value]).map((item) => {
+		if (typeof item === "string") return { type: item };
+		if (typeof item === "object" && item !== null && "type" in item) {
+			const type = item.type;
+			const params = "params" in item && typeof item.params === "object" && item.params ? item.params : void 0;
+			return {
+				type,
+				...params ? { params } : {}
+			};
+		}
+		return { type: String(item) };
+	});
+}
+function normalizeTags(value) {
+	if (!value) return [];
+	if (Array.isArray(value)) return value.map((tag) => String(tag));
+	return [String(value)];
+}
+function normalizeInvoke(value) {
+	if (!value) return [];
+	return (Array.isArray(value) ? value : [value]).map((invoke, index) => ({
+		src: invoke.src,
+		id: invoke.id ?? `invoke[${index}]`,
+		...invoke.input ? { input: invoke.input } : {}
+	}));
+}
+function resolveTargetId(sourceParentPath, target) {
+	if (!target) return;
+	if (target.startsWith("#")) {
+		const stripped = target.slice(1);
+		const machineIndex = stripped.indexOf(".");
+		if (machineIndex >= 0) return `(machine).${stripped.slice(machineIndex + 1)}`;
+		return `(machine).${stripped}`;
+	}
+	if (target.startsWith("(machine)")) return target;
+	if (target.includes(".")) return `(machine).${target}`;
+	return `${sourceParentPath}.${target}`;
+}
+function appendTransitionEdges(edges, sourceId, sourceParentPath, eventType, transition, edgeCounts) {
+	const transitions = Array.isArray(transition) ? transition : [transition];
+	for (const item of transitions) {
+		const normalized = typeof item === "string" ? { target: item } : item;
+		const targetId = resolveTargetId(sourceParentPath, Array.isArray(normalized.target) ? normalized.target[0] : normalized.target);
+		const groupKey = `${sourceId}:${eventType}`;
+		const index = edgeCounts.get(groupKey) ?? 0;
+		edgeCounts.set(groupKey, index + 1);
+		edges.push({
+			type: "edge",
+			id: `${sourceId}#${eventType}[${index}]`,
+			sourceId,
+			targetId: targetId ?? sourceId,
+			label: eventType,
+			data: {
+				eventType,
+				transitionType: normalized.reenter === true ? "reenter" : normalized.internal === true || !targetId ? "targetless" : "normal",
+				...normalized.guard ? { guard: typeof normalized.guard === "string" ? { type: normalized.guard } : {
+					type: normalized.guard.type,
+					...normalized.guard.params ? { params: normalized.guard.params } : {}
+				} } : {},
+				actions: normalizeActions(normalized.actions),
+				...normalized.description ? { description: normalized.description } : {}
+			}
+		});
+	}
+}
+function fromXStateConfig(config) {
+	const nodes = [];
+	const edges = [];
+	const edgeCounts = /* @__PURE__ */ new Map();
+	function visitNode(key, nodeConfig, parentId, parentPath) {
+		const nodeId = parentPath ? `${parentPath}.${key}` : "(machine)";
+		const currentPath = parentPath ? nodeId : "(machine)";
+		const initialId = nodeConfig.initial ? `${currentPath}.${nodeConfig.initial}` : void 0;
+		nodes.push({
+			type: "node",
+			id: nodeId,
+			parentId,
+			label: key,
+			...initialId ? { initialNodeId: initialId } : {},
+			data: {
+				key,
+				...nodeConfig.type ? { type: nodeConfig.type } : {},
+				...nodeConfig.history ? { history: nodeConfig.history } : {},
+				...initialId ? { initialId } : {},
+				entry: normalizeActions(nodeConfig.entry),
+				exit: normalizeActions(nodeConfig.exit),
+				invokes: normalizeInvoke(nodeConfig.invoke),
+				tags: normalizeTags(nodeConfig.tags),
+				...nodeConfig.description ? { description: nodeConfig.description } : {}
+			}
+		});
+		for (const [eventType, transition] of Object.entries(nodeConfig.on ?? {})) appendTransitionEdges(edges, nodeId, parentPath ?? "(machine)", eventType, transition, edgeCounts);
+		if (nodeConfig.always) appendTransitionEdges(edges, nodeId, parentPath ?? "(machine)", "", nodeConfig.always, edgeCounts);
+		for (const [childKey, childConfig] of Object.entries(nodeConfig.states ?? {})) visitNode(childKey, childConfig, nodeId, currentPath);
+	}
+	visitNode("(machine)", config, null, null);
+	return {
+		id: config.id ?? "machine",
+		nodes,
+		edges,
+		data: {}
+	};
+}
+async function resolveLocalFile(locator, options) {
+	const filePath = path.resolve(options.cwd ?? process.cwd(), locator);
+	const contents = await fs.readFile(filePath, "utf8");
+	const extension = path.extname(filePath).toLowerCase();
+	if (extension === ".ts" || extension === ".tsx" || extension === ".js" || extension === ".jsx") {
+		const config = (await (options.client ?? createStatelyClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})).code.extractMachines(contents)).machines[0]?.config;
+		if (!config) throw new Error(`No machines extracted from ${filePath}`);
+		return {
+			kind: "local-file",
+			locator: filePath,
+			format: "xstate",
+			graph: fromXStateConfig(config)
+		};
+	}
+	const parsed = JSON.parse(contents);
+	if ("rootNode" in parsed && "edges" in parsed) return {
+		kind: "local-file",
+		locator: filePath,
+		format: "digraph",
+		graph: fromStudioMachine(parsed)
+	};
+	if ("nodes" in parsed && "edges" in parsed) return {
+		kind: "local-file",
+		locator: filePath,
+		format: "graph",
+		graph: parsed
+	};
+	if ("states" in parsed) return {
+		kind: "local-file",
+		locator: filePath,
+		format: "xstate",
+		graph: fromXStateConfig(parsed)
+	};
+	throw new Error(`Unsupported local sync input: ${filePath}`);
+}
+function inferWritableTargetFormat(filePath) {
+	if (filePath.endsWith(".ts") || filePath.endsWith(".tsx") || filePath.endsWith(".js") || filePath.endsWith(".jsx")) return "xstate";
+	if (filePath.endsWith(".digraph.json")) return "digraph";
+	if (filePath.endsWith(".graph.json")) return "graph";
+	return null;
+}
+function serializeGraph(graph, format) {
+	switch (format) {
+		case "digraph": return `${JSON.stringify(toStudioMachine(graph), null, 2)}\n`;
+		case "graph": return `${JSON.stringify(graph, null, 2)}\n`;
+		case "xstate": return graphToXStateTS(graph);
+		default: {
+			const exhaustive = format;
+			throw new Error(`Unsupported sync output format: ${exhaustive}`);
+		}
+	}
+}
+async function resolveRemoteMachine(machineId, baseUrl, kind, locator, options) {
+	return {
+		kind,
+		locator,
+		format: "digraph",
+		graph: fromStudioMachine(await (options.client ?? createStatelyClient({
+			apiKey: options.apiKey,
+			baseUrl,
+			fetch: options.fetch
+		})).machines.get(machineId))
+	};
+}
+async function resolveSyncInput(locator, options) {
+	if (await fileExists(path.resolve(options.cwd ?? process.cwd(), locator))) return resolveLocalFile(locator, options);
+	if (isUrl(locator)) {
+		const url = new URL(locator);
+		const machineId = url.pathname.split("/").filter(Boolean).at(-1);
+		if (!machineId) throw new Error(`Could not resolve machine ID from URL: ${locator}`);
+		return resolveRemoteMachine(machineId, url.origin, "studio-url", locator, options);
+	}
+	return resolveRemoteMachine(locator, options.baseUrl, "studio-machine-id", locator, options);
+}
+function summarizeDiff(diff) {
+	const nodeChanges = diff.nodes.added.length + diff.nodes.removed.length + diff.nodes.updated.length;
+	const edgeChanges = diff.edges.added.length + diff.edges.removed.length + diff.edges.updated.length;
+	return {
+		hasChanges: !isEmptyDiff(diff),
+		nodeChanges,
+		edgeChanges
+	};
+}
+async function planSync(options) {
+	const source = await resolveSyncInput(options.source, options);
+	const target = await resolveSyncInput(options.target, options);
+	const diff = getDiff(source.graph, target.graph);
+	return {
+		source,
+		target,
+		diff,
+		summary: summarizeDiff(diff),
+		warnings: []
+	};
+}
+async function pullSync(options) {
+	const source = await resolveSyncInput(options.source, options);
+	const outputPath = path.resolve(options.cwd ?? process.cwd(), options.target);
+	const fallbackFormat = inferWritableTargetFormat(outputPath);
+	let targetFormat = fallbackFormat;
+	if (await fileExists(outputPath)) try {
+		targetFormat = (await resolveLocalFile(options.target, options)).format;
+	} catch (error) {
+		if (!fallbackFormat) throw error;
+	}
+	if (!targetFormat) throw new Error(`Could not infer a writable target format from ${outputPath}. Use an existing digraph/graph file or a .digraph.json/.graph.json target.`);
+	const serialized = serializeGraph(source.graph, targetFormat);
+	await fs.writeFile(outputPath, serialized, "utf8");
+	return {
+		source,
+		target: {
+			kind: "local-file",
+			locator: outputPath,
+			format: targetFormat,
+			graph: source.graph
+		},
+		outputPath
+	};
+}
+
+//#endregion
+export { pullSync as n, planSync as t };

package/dist/sync.d.mts

@@ -0,0 +1,43 @@
+import { i as StatelyGraph } from "./graph-C-7ZK_nK.mjs";
+import { StudioClient } from "./studio.mjs";
+import { GraphDiff } from "@statelyai/graph";
+
+//#region src/sync.d.ts
+interface PlanSyncOptions {
+  source: string;
+  target: string;
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  client?: StudioClient;
+  cwd?: string;
+}
+type ResolvedSyncInputKind = 'local-file' | 'studio-machine-id' | 'studio-url';
+type SyncInputFormat = 'digraph' | 'graph' | 'xstate';
+interface ResolvedSyncInput {
+  kind: ResolvedSyncInputKind;
+  locator: string;
+  format: SyncInputFormat;
+  graph: StatelyGraph;
+}
+interface SyncPlanSummary {
+  hasChanges: boolean;
+  nodeChanges: number;
+  edgeChanges: number;
+}
+interface SyncPlan {
+  source: ResolvedSyncInput;
+  target: ResolvedSyncInput;
+  diff: GraphDiff;
+  summary: SyncPlanSummary;
+  warnings: string[];
+}
+interface PullSyncResult {
+  source: ResolvedSyncInput;
+  target: ResolvedSyncInput;
+  outputPath: string;
+}
+declare function planSync(options: PlanSyncOptions): Promise<SyncPlan>;
+declare function pullSync(options: PlanSyncOptions): Promise<PullSyncResult>;
+//#endregion
+export { PlanSyncOptions, PullSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary, planSync, pullSync };

package/dist/sync.mjs

@@ -0,0 +1,5 @@
+import "./studio.mjs";
+import "./graph.mjs";
+import { n as pullSync, t as planSync } from "./sync-CzEOizjx.mjs";
+
+export { planSync, pullSync };