@statelyai/sdk 0.5.1 → 0.6.0

package/dist/sync.mjs

@@ -1,11 +1,14 @@
 import { createStatelyClient } from "./studio.mjs";
+import { d as upsertStatelyPragma, t as graphToXStateTS } from "./graphToXStateTS-CvXM8wHL.mjs";
 import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
-import { t as graphToXStateTS } from "./graphToXStateTS-CtecEESq.mjs";
 import { getDiff, isEmptyDiff } from "@statelyai/graph";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 
 //#region src/sync.ts
+const execFileAsync = promisify(execFile);
 function isUrl(value) {
 	try {
 		const url = new URL(value);
@@ -22,6 +25,62 @@ async function fileExists(filePath) {
 		return false;
 	}
 }
+function parseGitHubRemote(remoteUrl) {
+	const httpsMatch = remoteUrl.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (httpsMatch) {
+		const [, owner, repo] = httpsMatch;
+		if (!owner || !repo) return null;
+		return {
+			url: `https://github.com/${owner}/${repo}`,
+			owner,
+			repo
+		};
+	}
+	const sshMatch = remoteUrl.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (sshMatch) {
+		const [, owner, repo] = sshMatch;
+		if (!owner || !repo) return null;
+		return {
+			url: `https://github.com/${owner}/${repo}`,
+			owner,
+			repo
+		};
+	}
+	return null;
+}
+async function inferConnectedRepo(filePath, cwd) {
+	const workingDir = cwd ?? path.dirname(filePath);
+	try {
+		const [{ stdout: repoRootStdout }, { stdout: remoteStdout }, { stdout: branchStdout }, { stdout: treeShaStdout }] = await Promise.all([
+			execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd: workingDir }),
+			execFileAsync("git", [
+				"remote",
+				"get-url",
+				"origin"
+			], { cwd: workingDir }),
+			execFileAsync("git", ["branch", "--show-current"], { cwd: workingDir }),
+			execFileAsync("git", ["rev-parse", "HEAD"], { cwd: workingDir })
+		]);
+		const repoRoot = repoRootStdout.trim();
+		const remote = parseGitHubRemote(remoteStdout.trim());
+		const branch = branchStdout.trim();
+		const treeSha = treeShaStdout.trim();
+		if (!remote || !branch || !treeSha) return;
+		const relativePath = path.relative(repoRoot, filePath).replace(/\\/g, "/");
+		const relativeDir = path.dirname(relativePath).replace(/\\/g, "/");
+		const selectedPaths = relativePath && relativePath !== "." ? [relativePath] : [];
+		return {
+			...remote,
+			branch,
+			treeSha,
+			autoSync: false,
+			pathForNewFiles: relativeDir && relativeDir !== "." ? relativeDir : "src/stately-studio",
+			selectedPaths
+		};
+	} catch {
+		return;
+	}
+}
 function normalizeActions(value) {
 	if (value == null) return [];
 	return (Array.isArray(value) ? value : [value]).map((item) => {
@@ -172,11 +231,15 @@ function inferWritableTargetFormat(filePath) {
 	if (filePath.endsWith(".graph.json")) return "graph";
 	return null;
 }
-function serializeGraph(graph, format) {
+function serializeGraph(graph, format, options = {}) {
 	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);
+		case "xstate": {
+			const source = graphToXStateTS(graph);
+			if (!options.remoteMachineId) return source;
+			return upsertStatelyPragma(source, options.remoteMachineId, options.targetPath ? { fileName: options.targetPath } : {});
+		}
 		default: {
 			const exhaustive = format;
 			throw new Error(`Unsupported sync output format: ${exhaustive}`);
@@ -192,7 +255,8 @@ async function resolveRemoteMachine(machineId, baseUrl, kind, locator, options)
 			apiKey: options.apiKey,
 			baseUrl,
 			fetch: options.fetch
-		})).machines.get(machineId))
+		})).machines.get(machineId)),
+		remoteMachineId: machineId
 	};
 }
 async function resolveSyncInput(locator, options) {
@@ -237,7 +301,10 @@ async function pullSync(options) {
 		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);
+	const serialized = serializeGraph(source.graph, targetFormat, {
+		remoteMachineId: source.remoteMachineId,
+		targetPath: outputPath
+	});
 	await fs.writeFile(outputPath, serialized, "utf8");
 	return {
 		source,
@@ -250,6 +317,61 @@ async function pullSync(options) {
 		outputPath
 	};
 }
+function inferDefaultProjectName(sourcePath, repo) {
+	if (repo?.repo) return repo.repo;
+	const parentDir = path.basename(path.dirname(sourcePath));
+	if (parentDir && parentDir !== ".") return parentDir;
+	return path.basename(sourcePath, path.extname(sourcePath));
+}
+async function resolvePushProject(client, sourcePath, options) {
+	const explicitProject = options.project;
+	if (explicitProject?.projectVersionId) return client.projects.get(explicitProject.projectVersionId);
+	if (explicitProject?.projectId) return client.projects.get(explicitProject.projectId);
+	const inferredRepo = explicitProject?.repo ?? await inferConnectedRepo(sourcePath, options.cwd);
+	const projectInput = {
+		name: explicitProject?.name ?? inferDefaultProjectName(sourcePath, inferredRepo),
+		visibility: explicitProject?.visibility ?? "Private",
+		...explicitProject?.description ? { description: explicitProject.description } : {},
+		...explicitProject?.keywords ? { keywords: explicitProject.keywords } : {},
+		...inferredRepo ? { repo: inferredRepo } : {}
+	};
+	return client.projects.ensure(projectInput);
+}
+async function pushSync(options) {
+	const client = options.client ?? createStatelyClient({
+		apiKey: options.apiKey,
+		baseUrl: options.baseUrl,
+		fetch: options.fetch
+	});
+	const source = await resolveSyncInput(options.source, {
+		...options,
+		target: options.source
+	});
+	if (source.kind !== "local-file") throw new Error("pushSync currently requires a local source file.");
+	const sourcePath = source.locator;
+	const project = await resolvePushProject(client, sourcePath, options);
+	if (!project.projectVersionId) throw new Error("Resolved project is missing projectVersionId.");
+	const machine = await client.machines.create({
+		projectVersionId: project.projectVersionId,
+		definition: toStudioMachine(source.graph),
+		xstateVersion: options.xstateVersion ?? 5
+	});
+	let outputPath;
+	if (source.format === "xstate") {
+		const contents = await fs.readFile(sourcePath, "utf8");
+		const nextContents = upsertStatelyPragma(contents, machine.id, { fileName: sourcePath });
+		if (nextContents !== contents) {
+			await fs.writeFile(sourcePath, nextContents, "utf8");
+			outputPath = sourcePath;
+		}
+	}
+	return {
+		source,
+		project,
+		machine,
+		...outputPath ? { outputPath } : {}
+	};
+}
 
 //#endregion
-export { planSync, pullSync };
+export { planSync, pullSync, pushSync };

package/dist/{transport-DoCHBLTu.mjs → transport-C0eTgNNu.mjs}

@@ -89,6 +89,20 @@ function createPendingExportManager(sendRetrieve) {
 	};
 }
 function toInitMessage(options) {
+	if ("machines" in options) return {
+		type: "@statelyai.project.init",
+		machines: options.machines,
+		currentMachineId: options.currentMachineId,
+		mode: options.mode,
+		theme: options.theme,
+		readOnly: options.readOnly,
+		depth: options.depth,
+		leftPanels: options.panels?.leftPanels,
+		rightPanels: options.panels?.rightPanels,
+		activePanels: options.panels?.activePanels,
+		commentsByMachineId: options.commentsByMachineId,
+		unsavedIndicator: options.unsavedIndicator
+	};
 	return {
 		type: "@statelyai.init",
 		machine: options.machine,

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "MIT",
-  "files": [
-    "dist"
-  ],
-  "type": "module",
   "bin": {
     "statelyai": "./dist/cli.mjs"
   },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -43,21 +44,20 @@
     "./studio": {
       "types": "./dist/studio.d.mts",
       "import": "./dist/studio.mjs"
-    }
+    },
+    "./api": {
+      "types": "./dist/api.d.mts",
+      "import": "./dist/api.mjs"
+    },
+    "./statelyai.schema.json": "./schemas/statelyai.schema.json",
+    "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json"
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",
     "@statelyai/graph": "^0.9.0",
     "typescript": "^5.9.3",
-    "xstate": "^5.0.0"
-  },
-  "oclif": {
-    "bin": "statelyai",
-    "commands": {
-      "strategy": "explicit",
-      "target": "./dist/cli.mjs",
-      "identifier": "COMMANDS"
-    }
+    "xstate": "^5.0.0",
+    "@statelyai/graph-tools": "0.0.0"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
@@ -65,6 +65,15 @@
     "tsdown": "0.21.0-beta.2",
     "vitest": "^3.2.4"
   },
+  "oclif": {
+    "bin": "statelyai",
+    "commands": {
+      "identifier": "COMMANDS",
+      "strategy": "explicit",
+      "target": "./dist/cli.mjs"
+    },
+    "topicSeparator": " "
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",

package/schemas/statelyai.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stately.ai/schemas/statelyai.json",
+  "title": "Stately CLI project configuration",
+  "description": "Configuration for mapping local machine sources to a Stately Studio project.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "projectId", "sources"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri-reference",
+      "description": "Optional self-reference to this schema."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "Schema version for statelyai.json, expressed as a semantic version string."
+    },
+    "projectId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable Stately Studio project identifier."
+    },
+    "studioUrl": {
+      "type": "string",
+      "format": "uri",
+      "default": "https://stately.ai",
+      "description": "Base URL of the Studio instance that owns the project."
+    },
+    "defaultXStateVersion": {
+      "type": "integer",
+      "minimum": 5,
+      "default": 5,
+      "description": "Default XState major version for sources that do not override it. Only XState 5+ is supported."
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Source groups used to discover and classify local machine files.",
+      "items": {
+        "$ref": "#/$defs/source"
+      }
+    }
+  },
+  "$defs": {
+    "globPattern": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A glob pattern evaluated relative to the statelyai.json location."
+    },
+    "sourceFormat": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "xstate",
+        "json",
+        "xgraph",
+        "digraph",
+        "mermaid",
+        "scxml",
+        "asl-json",
+        "asl-yaml",
+        "redux",
+        "zustand"
+      ],
+      "description": "Machine format for matching sources. Use xstate for JavaScript or TypeScript machine source files."
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["include"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional label for this source group."
+        },
+        "include": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/globPattern"
+          },
+          "description": "Glob patterns for files to include in this source group."
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/globPattern"
+          },
+          "description": "Glob patterns excluded from this source group."
+        },
+        "format": {
+          "$ref": "#/$defs/sourceFormat",
+          "default": "auto"
+        },
+        "xstateVersion": {
+          "type": "integer",
+          "minimum": 5,
+          "description": "Optional XState major version override for this source group. Only XState 5+ is supported."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "$schema": "https://stately.ai/schemas/statelyai.json",
+      "version": "1.0.0",
+      "projectId": "project_123",
+      "studioUrl": "https://stately.ai",
+      "defaultXStateVersion": 5,
+      "sources": [
+        {
+          "name": "app-machines",
+          "include": ["src/**/*.ts", "src/**/*.tsx"],
+          "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/dist/**"],
+          "format": "xstate"
+        },
+        {
+          "name": "docs",
+          "include": ["docs/**/*.mmd"],
+          "format": "mermaid"
+        }
+      ]
+    }
+  ]
+}