@statelyai/sdk 0.6.1 → 0.7.0

package/README.md

@@ -206,12 +206,15 @@ Available client methods:
 | `studio.projects.get(projectId)`                                        | Fetch a project and its machines                                         |
 | `studio.machines.create({ projectVersionId, ... })`                     | Create a machine through the published REST API                          |
 | `studio.machines.createMany({ projectVersionId, ... })`                 | Compatibility wrapper around `create()` that returns a one-item array    |
+| `studio.machines.update({ id, ... })`                                   | Update a machine through the published REST API                          |
 | `studio.machines.get(machineId, { version? })`                          | Fetch a machine, optionally pinned to a version                          |
 | `studio.code.extractMachines(code, { apiKey? })`                        | Extract machine configs from source text                                 |
 
 ## Sync Helpers
 
-`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, creates the remote machine, and writes `// @statelyai id=...` back into XState source files.
+`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, updates the linked remote machine when `// @statelyai id=...` is present, otherwise creates one, and writes the pragma back into XState source files when needed.
+
+For project-scoped discovery flows, `statelyai.json` defines which local files should be scanned. The CLI `statelyai push` command uses that config to find local XState sources, creates remote Studio machines for unlabeled ones, updates already-linked ones, and writes returned `// @statelyai id=...` pragmas back into source.
 
 ```ts
 import { pushSync } from '@statelyai/sdk/sync';
@@ -232,7 +235,7 @@ const result = await pushSync({
 });
 ```
 
-Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`.
+Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`. The strict XState JSON export schema is published at `@statelyai/sdk/xstate-json.schema.json`.
 
 ```json
 {
@@ -241,17 +244,7 @@ Projects can also check in a `statelyai.json` file to describe which local sourc
   "projectId": "project_123",
   "studioUrl": "https://stately.ai",
   "defaultXStateVersion": 5,
-  "sources": [
-    {
-      "include": ["src/**/*.ts", "src/**/*.tsx"],
-      "exclude": ["**/*.test.ts", "**/dist/**"],
-      "format": "xstate"
-    },
-    {
-      "include": ["docs/**/*.mmd"],
-      "format": "mermaid"
-    }
-  ]
+  "sources": []
 }
 ```
 
@@ -423,7 +416,7 @@ const aslYaml = await embed.export('asl-yaml');
 
 <!-- supported export formats from ExportFormatMap in src/protocol.ts -->
 
-Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
+Supported formats: `xstate`, `xstate-json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
@@ -605,11 +598,15 @@ Installing the package also exposes a `statelyai` binary:
 npx statelyai open ./checkout.machine.ts
 
 statelyai init
+statelyai init --scan
 statelyai login
 statelyai auth status
 statelyai plan ./checkout.machine.ts machine-id
 statelyai diff ./checkout.machine.ts machine-id --fail-on-changes
+statelyai push
+statelyai push ./checkout.machine.ts
 statelyai pull machine-id ./checkout.machine.ts
+statelyai pull ./checkout.machine.ts
 statelyai open ./checkout.machine.ts
 ```
 
@@ -619,13 +616,15 @@ Available commands:
 
 | Command                            | Description                                                                 |
 | ---------------------------------- | --------------------------------------------------------------------------- |
-| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` |
+| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` with an empty `sources` array |
 | `statelyai login`                  | Store an API key for future CLI use                                         |
 | `statelyai logout`                 | Remove a stored API key                                                     |
 | `statelyai auth status`            | Show whether the CLI would use an environment variable or stored credential |
 | `statelyai plan <source> <target>` | Print a semantic sync summary                                               |
 | `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes                            |
+| `statelyai push [file]`            | Discover local machine sources, create remote Studio machines for unlabeled files, update linked ones, and persist returned ids |
 | `statelyai pull <source> <target>` | Materialize a source into a local target file                               |
+| `statelyai pull <linked-file>`     | Refresh a linked local file from the `@statelyai id=...` pragma             |
 | `statelyai open <file>`            | Open a local file in a browser-backed visual editor session                 |
 
 Common flags:
@@ -636,6 +635,8 @@ Common flags:
 
 The CLI resolves credentials in this order: `--api-key`, then `STATELY_API_KEY`/`NEXT_PUBLIC_STATELY_API_KEY`, then the key stored by `statelyai login`. `login` stores the key in the OS credential store when available, with a private file fallback.
 
+`statelyai init --scan` walks local code files, detects machine-bearing files from their contents, and suggests `sources` globs to save into `statelyai.json`. Without `--scan`, `init` leaves `sources` empty so you can opt in explicitly before running `statelyai push`.
+
 `statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. When the source file contains `// @statelyai id=...` and an API key is available, the editor session also reuses the referenced remote machine layout while continuing to treat the local source as the semantic source of truth. Pass `--api-key`, set `STATELY_API_KEY`, or run `statelyai login` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
 
 ## Transport Helpers

package/dist/assetStorage.d.mts

@@ -1,4 +1,4 @@
-import { m as UploadResult } from "./protocol-CDoCcaIP.mjs";
+import { m as UploadResult } from "./protocol-DN4mH4jR.mjs";
 
 //#region src/assetStorage.d.ts
 interface AssetUploadContext {

package/dist/cli.d.mts

@@ -4,11 +4,11 @@ import { SyncPlan } from "./sync.mjs";
 import { Command } from "@oclif/core";
 import * as _oclif_core_interfaces0 from "@oclif/core/interfaces";
 
-//#region src/cli.d.ts
+//#region src/projectConfig.d.ts
 interface StatelySourceConfig {
   include: string[];
   exclude?: string[];
-  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'json' | 'asl-json' | 'asl-yaml' | 'auto';
+  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'xstate-json' | 'asl-json' | 'asl-yaml' | 'auto';
   xstateVersion?: number;
 }
 interface StatelyProjectConfig {
@@ -19,6 +19,13 @@ interface StatelyProjectConfig {
   defaultXStateVersion: number;
   sources: StatelySourceConfig[];
 }
+declare function createStatelyProjectConfig(options: {
+  projectId: string;
+  studioUrl: string;
+  defaultXStateVersion?: number;
+}): StatelyProjectConfig;
+//#endregion
+//#region src/cli.d.ts
 interface InitProjectOptions {
   apiKey: string;
   baseUrl?: string;
@@ -34,11 +41,11 @@ interface InitProjectResult {
   configPath: string;
   project: ProjectData;
 }
-declare function createStatelyProjectConfig(options: {
-  projectId: string;
-  studioUrl: string;
+interface ScanProjectSourcesOptions {
+  cwd?: string;
+  client: StudioClient;
   defaultXStateVersion?: number;
-}): StatelyProjectConfig;
+}
 type ApiKeyResolution = {
   apiKey: string;
   detail: string;
@@ -55,6 +62,7 @@ declare function getEnvApiKey(): {
 declare function resolveApiKey(explicitApiKey?: string): Promise<ApiKeyResolution>;
 declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
+declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<StatelySourceConfig[]>;
 declare function formatPlanSummary(plan: SyncPlan): string;
 declare abstract class BaseSyncCommand extends Command {
   static enableJsonFlag: boolean;
@@ -100,7 +108,22 @@ declare class PullCommand extends ParsedSyncCommand {
   static description: string;
   static args: {
     source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
-    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare class PushCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    file: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  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>;
+    config: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }
@@ -133,6 +156,7 @@ declare class InitCommand extends Command {
     name: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
     visibility: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
     force: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    scan: _oclif_core_interfaces0.BooleanFlag<boolean>;
   };
   run(): Promise<void>;
 }
@@ -169,6 +193,7 @@ declare const COMMANDS: {
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
   pull: typeof PullCommand;
+  push: typeof PushCommand;
   open: typeof OpenCommand;
   init: typeof InitCommand;
   login: typeof LoginCommand;
@@ -177,4 +202,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: string[], entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, StatelyProjectConfig, StatelySourceConfig, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, ScanProjectSourcesOptions, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run, scanProjectSources };

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createStatelyClient } from "./studio.mjs";
-import "./graphToXStateTS-Gzh0ZqbN.mjs";
-import { planSync, pullSync } from "./sync.mjs";
+import { u as getStatelyPragma } from "./graphToXStateTS-Gzh0ZqbN.mjs";
+import { planSync, pullSync, pushLocalMachineLinks } from "./sync.mjs";
 import fs from "node:fs/promises";
 import * as path$1 from "node:path";
 import path from "node:path";
@@ -931,24 +931,26 @@ function describeCredentialBackend(backend, location) {
 }
 
 //#endregion
-//#region src/cli.ts
-const execFileAsync = promisify(execFile);
+//#region src/projectConfig.ts
 const STATELY_CONFIG_FILE = "statelyai.json";
 const STATELY_CONFIG_SCHEMA_URL = "https://stately.ai/schemas/statelyai.json";
 const STATELY_CONFIG_VERSION = "1.0.0";
-function getDefaultSources(defaultXStateVersion) {
-	return [{
-		include: ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
-		exclude: [
-			"**/*.test.*",
-			"**/*.spec.*",
-			"**/dist/**",
-			"**/node_modules/**"
-		],
-		format: "xstate",
-		xstateVersion: defaultXStateVersion
-	}];
-}
+const DEFAULT_SOURCE_EXCLUDES = [
+	"**/*.test.*",
+	"**/*.spec.*",
+	"**/dist/**",
+	"**/node_modules/**"
+];
+const CODE_SOURCE_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mts",
+	".cts",
+	".mjs",
+	".cjs"
+]);
 function createStatelyProjectConfig(options) {
 	const defaultXStateVersion = options.defaultXStateVersion ?? 5;
 	return {
@@ -957,9 +959,145 @@ function createStatelyProjectConfig(options) {
 		projectId: options.projectId,
 		studioUrl: options.studioUrl,
 		defaultXStateVersion,
-		sources: getDefaultSources(defaultXStateVersion)
+		sources: []
 	};
 }
+async function readStatelyProjectConfig(options = {}) {
+	const rootDir = path.resolve(options.cwd ?? process.cwd());
+	const configPath = path.resolve(rootDir, options.configPath ?? STATELY_CONFIG_FILE);
+	const raw = await fs.readFile(configPath, "utf8");
+	return {
+		config: JSON.parse(raw),
+		configPath,
+		rootDir
+	};
+}
+async function walkFiles(rootDir, currentDir = rootDir) {
+	const entries = await fs.readdir(currentDir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		if (entry.name === ".git") continue;
+		const absolutePath = path.join(currentDir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await walkFiles(rootDir, absolutePath));
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		files.push(path.relative(rootDir, absolutePath).replace(/\\/g, "/"));
+	}
+	return files;
+}
+function isCodeSourceFile(relativePath) {
+	return CODE_SOURCE_EXTENSIONS.has(path.extname(relativePath).toLowerCase());
+}
+function expandBraces(pattern) {
+	const match = pattern.match(/\{([^{}]+)\}/);
+	if (!match || match.index == null) return [pattern];
+	const [token, inner] = match;
+	return inner.split(",").flatMap((variant) => expandBraces(`${pattern.slice(0, match.index)}${variant}${pattern.slice(match.index + token.length)}`));
+}
+function globToRegExp(pattern) {
+	let regex = "^";
+	for (let index = 0; index < pattern.length; index += 1) {
+		const char = pattern[index];
+		const next = pattern[index + 1];
+		if (char === "*") {
+			if (next === "*") {
+				const slashAfterGlobstar = pattern[index + 2] === "/";
+				regex += slashAfterGlobstar ? "(?:.*/)?" : ".*";
+				index += slashAfterGlobstar ? 2 : 1;
+				continue;
+			}
+			regex += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			regex += "[^/]";
+			continue;
+		}
+		if ("\\.[]{}()+-^$|".includes(char)) {
+			regex += `\\${char}`;
+			continue;
+		}
+		regex += char;
+	}
+	regex += "$";
+	return new RegExp(regex);
+}
+function matchesGlob(relativePath, pattern) {
+	return expandBraces(pattern).some((expanded) => globToRegExp(expanded).test(relativePath));
+}
+function matchesAny(patterns, relativePath) {
+	return (patterns ?? []).some((pattern) => matchesGlob(relativePath, pattern));
+}
+async function discoverCodeSourceFiles(options = {}) {
+	return (await walkFiles(path.resolve(options.cwd ?? process.cwd()))).filter((relativePath) => isCodeSourceFile(relativePath)).filter((relativePath) => !matchesAny(DEFAULT_SOURCE_EXCLUDES, relativePath)).sort((left, right) => left.localeCompare(right));
+}
+function createSuggestedSource(include) {
+	return {
+		include: [include],
+		exclude: [...DEFAULT_SOURCE_EXCLUDES],
+		format: "xstate",
+		xstateVersion: 5
+	};
+}
+function suggestStatelySourceConfigs(relativePaths, defaultXStateVersion = 5) {
+	const pending = new Set(relativePaths.map((relativePath) => relativePath.replace(/\\/g, "/")).filter(Boolean));
+	const suggestions = [];
+	const addSuggestion = (include, predicate) => {
+		const matched = [...pending].filter(predicate);
+		if (matched.length === 0) return;
+		suggestions.push({
+			...createSuggestedSource(include),
+			xstateVersion: defaultXStateVersion
+		});
+		for (const matchedPath of matched) pending.delete(matchedPath);
+	};
+	addSuggestion("**/*.machine.ts", (relativePath) => relativePath.endsWith(".machine.ts"));
+	addSuggestion("src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}", (relativePath) => relativePath.startsWith("src/"));
+	addSuggestion("packages/*/src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}", (relativePath) => /^packages\/[^/]+\/src\//.test(relativePath));
+	addSuggestion("apps/*/src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}", (relativePath) => /^apps\/[^/]+\/src\//.test(relativePath));
+	const byDirectory = /* @__PURE__ */ new Map();
+	for (const relativePath of pending) {
+		const directory = path.posix.dirname(relativePath);
+		const key = directory === "." ? relativePath : directory;
+		const bucket = byDirectory.get(key) ?? [];
+		bucket.push(relativePath);
+		byDirectory.set(key, bucket);
+	}
+	for (const [key, matchedPaths] of [...byDirectory.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
+		if (matchedPaths.length > 1 && key !== "." && key !== matchedPaths[0]) {
+			addSuggestion(`${key}/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}`, (relativePath) => relativePath.startsWith(`${key}/`));
+			continue;
+		}
+		const exactPath = matchedPaths[0];
+		addSuggestion(exactPath, (relativePath) => relativePath === exactPath);
+	}
+	return suggestions;
+}
+async function discoverStatelySourceFiles(options = {}) {
+	const { config, rootDir } = options.config ? {
+		config: options.config,
+		rootDir: path.resolve(options.cwd ?? process.cwd())
+	} : await readStatelyProjectConfig(options);
+	const relativeFiles = await walkFiles(rootDir);
+	const discovered = /* @__PURE__ */ new Map();
+	for (const source of config.sources) for (const relativePath of relativeFiles) {
+		if (!matchesAny(source.include, relativePath)) continue;
+		if (matchesAny(source.exclude, relativePath)) continue;
+		const filePath = path.join(rootDir, relativePath);
+		if (!discovered.has(filePath)) discovered.set(filePath, {
+			filePath,
+			relativePath,
+			source
+		});
+	}
+	return [...discovered.values()].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+//#endregion
+//#region src/cli.ts
+const execFileAsync = promisify(execFile);
 function loadLocalEnv() {
 	if (typeof process.loadEnvFile !== "function") return;
 	const cwdEnvPath = path.join(process.cwd(), ".env.local");
@@ -1090,6 +1228,22 @@ async function promptForApiKey() {
 		rl.close();
 	}
 }
+async function promptYesNo(question, defaultValue = true) {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("No interactive terminal available.");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		terminal: true
+	});
+	try {
+		const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
+		const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+		if (!answer) return defaultValue;
+		return answer === "y" || answer === "yes";
+	} finally {
+		rl.close();
+	}
+}
 function normalizeApiKey(value) {
 	const trimmed = value?.trim();
 	return trimmed ? trimmed : void 0;
@@ -1133,6 +1287,45 @@ async function initProject(options) {
 		project
 	};
 }
+async function scanProjectSources(options) {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const candidateRelativePaths = await discoverCodeSourceFiles({ cwd });
+	const machineRelativePaths = [];
+	for (const relativePath of candidateRelativePaths) {
+		const filePath = path.join(cwd, relativePath);
+		const contents = await fs.readFile(filePath, "utf8");
+		let extracted;
+		try {
+			extracted = await options.client.code.extractMachines(contents);
+		} catch {
+			continue;
+		}
+		if (extracted.machines.length > 0) machineRelativePaths.push(relativePath);
+	}
+	return suggestStatelySourceConfigs(machineRelativePaths, Math.max(5, options.defaultXStateVersion ?? 5));
+}
+function supportsMachineDiscovery(file) {
+	return file.source.format === "xstate" || file.source.format === "auto";
+}
+async function resolveConfiguredProject(options) {
+	const { config, configPath, rootDir } = await readStatelyProjectConfig({
+		cwd: options.cwd,
+		configPath: options.configPath
+	});
+	const studioUrl = options.baseUrl ?? config.studioUrl;
+	return {
+		client: options.client ?? createStatelyClient({
+			apiKey: options.apiKey,
+			baseUrl: studioUrl
+		}),
+		config,
+		configPath,
+		files: await discoverStatelySourceFiles({
+			cwd: rootDir,
+			config
+		})
+	};
+}
 const sharedFlags = {
 	help: Flags.help({ char: "h" }),
 	"fail-on-changes": Flags.boolean({
@@ -1225,19 +1418,99 @@ var DiffCommand = class DiffCommand extends ParsedSyncCommand {
 var PullCommand = class PullCommand extends ParsedSyncCommand {
 	static summary = "Pull a source locator into a local target file.";
 	static description = "Resolves the source, materializes it in the target format inferred from the target file, and writes the result locally.";
-	static args = sharedArgs;
+	static args = {
+		source: Args.string({
+			required: true,
+			description: "Source locator. Supports a local linked file, machine ID, URL, or local file path."
+		}),
+		target: Args.string({
+			required: false,
+			description: "Optional local target path. Defaults to the source file when pulling a linked local file."
+		})
+	};
 	async run() {
 		const { args, flags } = await this.parseSync(PullCommand);
 		const apiKey = (await resolveApiKey(flags["api-key"])).apiKey;
+		const localCandidate = path.resolve(process.cwd(), args.source);
+		let source = args.source;
+		let target = args.target;
+		if (!target && await fileExists(localCandidate)) {
+			const pragma = getStatelyPragma(await fs.readFile(localCandidate, "utf8"), localCandidate);
+			if (!pragma?.id) this.error(`No @statelyai id found in ${localCandidate}. Pass an explicit source machine ID or URL and target path.`);
+			source = pragma.id;
+			target = localCandidate;
+		}
+		if (!target) this.error("Missing target path. Pass `statelyai pull <machine-id|url> <file>` or `statelyai pull <linked-file>`.");
 		const result = await pullSync({
-			source: args.source,
-			target: args.target,
+			source,
+			target,
 			apiKey,
 			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
 		});
 		this.log(`Pulled: ${result.source.locator} -> ${result.outputPath}\nTarget: ${result.target.kind} (${result.target.format})`);
 	}
 };
+var PushCommand = class PushCommand extends Command {
+	static enableJsonFlag = false;
+	static summary = "Create or update remote machines for local source files.";
+	static description = "Uses statelyai.json source discovery by default, creates remote machines for unlabeled local machine sources, updates already-linked machines, and writes returned @statelyai ids back into source files.";
+	static args = { file: Args.string({
+		required: false,
+		description: "Optional local source file to push instead of scanning statelyai.json."
+	}) };
+	static flags = {
+		help: Flags.help({ char: "h" }),
+		"api-key": Flags.string({ description: "Stately API key used to create or update remote machines" }),
+		"base-url": Flags.string({ description: "Base URL for Stately Studio or a self-hosted deployment" }),
+		config: Flags.string({ description: "Path to statelyai.json" })
+	};
+	async run() {
+		const { args, flags } = await this.parse(PushCommand);
+		const resolvedApiKey = await resolveApiKey(flags["api-key"]);
+		if (!resolvedApiKey.apiKey) this.error("No API key configured. Use `statelyai login`, set `STATELY_API_KEY`, or pass `--api-key`.");
+		const { client, config, files } = await resolveConfiguredProject({
+			apiKey: resolvedApiKey.apiKey,
+			baseUrl: flags["base-url"],
+			configPath: flags.config
+		});
+		const candidateFiles = args.file ? [{
+			filePath: path.resolve(args.file),
+			relativePath: path.relative(process.cwd(), path.resolve(args.file)),
+			source: {
+				include: [args.file],
+				format: "xstate",
+				xstateVersion: config.defaultXStateVersion
+			}
+		}] : files.filter(supportsMachineDiscovery);
+		if (candidateFiles.length === 0) {
+			this.log("No matching local machine source files were discovered.");
+			return;
+		}
+		const linked = [];
+		const refreshed = [];
+		const skipped = [];
+		for (const file of candidateFiles) {
+			if (!supportsMachineDiscovery(file)) {
+				skipped.push(`${file.relativePath}: unsupported format ${file.source.format}`);
+				continue;
+			}
+			const result = await pushLocalMachineLinks({
+				source: file.filePath,
+				apiKey: resolvedApiKey.apiKey,
+				baseUrl: flags["base-url"] ?? config.studioUrl,
+				client,
+				project: { projectId: config.projectId },
+				xstateVersion: Math.max(5, file.source.xstateVersion ?? config.defaultXStateVersion)
+			});
+			if (result.created.length > 0) linked.push(`${file.relativePath}: ${result.created.map(({ machineIndex, machine }) => `${machine.id} [${machineIndex}]`).join(", ")}`);
+			if (result.updated.length > 0) refreshed.push(`${file.relativePath}: ${result.updated.map(({ machineIndex, machine }) => `${machine.id} [${machineIndex}]`).join(", ")}`);
+			for (const entry of result.skipped) skipped.push(`${file.relativePath} [${entry.machineIndex}]: ${entry.reason}`);
+		}
+		if (linked.length > 0) this.log(`Linked:\n${linked.join("\n")}`);
+		if (refreshed.length > 0) this.log(`Updated:\n${refreshed.join("\n")}`);
+		if (skipped.length > 0) this.log(`Skipped:\n${skipped.join("\n")}`);
+	}
+};
 var OpenCommand = class OpenCommand extends Command {
 	static enableJsonFlag = false;
 	static summary = "Open a local file in the Stately visual editor.";
@@ -1304,6 +1577,10 @@ var InitCommand = class InitCommand extends Command {
 		force: Flags.boolean({
 			description: "Overwrite an existing statelyai.json file",
 			default: false
+		}),
+		scan: Flags.boolean({
+			description: "Scan the repo for machine-bearing files and suggest source globs to save into statelyai.json",
+			default: false
 		})
 	};
 	async run() {
@@ -1319,7 +1596,33 @@ var InitCommand = class InitCommand extends Command {
 				visibility: flags.visibility
 			}
 		});
-		this.log(`Initialized project ${result.project.projectId} and wrote ${result.configPath}.`);
+		if (flags.scan) {
+			const scanClient = createStatelyClient({
+				apiKey: resolvedApiKey.apiKey,
+				baseUrl: flags["base-url"] ?? result.config.studioUrl
+			});
+			const suggestions = await scanProjectSources({
+				cwd: path.dirname(result.configPath),
+				client: scanClient,
+				defaultXStateVersion: result.config.defaultXStateVersion
+			});
+			if (suggestions.length === 0) {
+				this.log(`Initialized project ${result.project.projectId} and wrote ${result.configPath}.\nNo machine source globs were suggested. Edit statelyai.json before running statelyai push.`);
+				return;
+			}
+			this.log(`Initialized project ${result.project.projectId} and wrote ${result.configPath}.`);
+			this.log(`Suggested source globs:\n${suggestions.map((source) => `- ${source.include.join(", ")}`).join("\n")}`);
+			if (await promptYesNo("Save these source globs to statelyai.json?", true)) {
+				const nextConfig = {
+					...result.config,
+					sources: suggestions
+				};
+				await fs.writeFile(result.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+				this.log("Saved scanned source globs to statelyai.json.");
+			} else this.log("Left statelyai.json with an empty sources array. Edit it before running statelyai push.");
+			return;
+		}
+		this.log(`Initialized project ${result.project.projectId} and wrote ${result.configPath}.\nNo source globs configured yet. Edit statelyai.json before running statelyai push, or rerun with --scan.`);
 	}
 };
 var LoginCommand = class LoginCommand extends Command {
@@ -1381,6 +1684,7 @@ const COMMANDS = {
 	plan: PlanCommand,
 	diff: DiffCommand,
 	pull: PullCommand,
+	push: PushCommand,
 	open: OpenCommand,
 	init: InitCommand,
 	login: LoginCommand,
@@ -1409,4 +1713,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run();
 
 //#endregion
-export { COMMANDS, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run };
+export { COMMANDS, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run, scanProjectSources };

package/dist/embed.d.mts

@@ -1,4 +1,4 @@
-import { a as EmbedMode, c as ExportFormatMap, d as MachineSourceLocations, f as ProjectEmbedMachine, i as EmbedEventName, l as InitOptions, m as UploadResult, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig, u as MachineInitOptions } from "./protocol-CDoCcaIP.mjs";
+import { a as EmbedMode, c as ExportFormatMap, d as MachineSourceLocations, f as ProjectEmbedMachine, i as EmbedEventName, l as InitOptions, m as UploadResult, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig, u as MachineInitOptions } from "./protocol-DN4mH4jR.mjs";
 import { AssetUploadAdapter } from "./assetStorage.mjs";
 
 //#region src/embed.d.ts

package/dist/embed.mjs

@@ -1,4 +1,4 @@
-import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-C0eTgNNu.mjs";
+import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-C8UTS3Fa.mjs";
 
 //#region src/embed.ts
 function buildEmbedUrl(options) {

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { StatelyApiClientOptions, StatelyApiError, StatelyApiUrlOptions, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";
-import { a as EmbedMode, c as ExportFormatMap, f as ProjectEmbedMachine, i as EmbedEventName, l as InitOptions, m as UploadResult, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig } from "./protocol-CDoCcaIP.mjs";
+import { a as EmbedMode, c as ExportFormatMap, f as ProjectEmbedMachine, i as EmbedEventName, l as InitOptions, m as UploadResult, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig } from "./protocol-DN4mH4jR.mjs";
 import { AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, VerifyApiKeyResponse, XStateVersion, createStatelyClient } from "./studio.mjs";
+import { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, UpdateMachineInput, VerifyApiKeyResponse, XStateVersion, createStatelyClient } from "./studio.mjs";
 import { C as EventTypeData, S as DigraphNodeConfig, _ as studioMachineConverter, a as StatelyGraphData, b as DigraphConfig, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, o as StatelyGuard, r as StatelyEdgeData, t as StatelyAction, v as toStudioMachine, w as StateNodeJSONData, x as DigraphEdgeConfig, y as DigraphAction } from "./graph-DpBGHZwl.mjs";
-import { PlanSyncOptions, PullSyncResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
+import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
-import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-BMIJcsFh.mjs";
+import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-Bg9FTvb3.mjs";
 import { ActionLocation, GraphPatch } from "./patchTypes.mjs";
 import { JSONSchema7 } from "json-schema";
 import { UnknownMachineConfig } from "xstate";
@@ -185,4 +185,4 @@ declare function contextSchemaToTSType(context: Record<string, JSONSchema7> | nu
  */
 declare function eventsSchemaToTSType(events: Record<string, JSONSchema7> | null | undefined): string | null;
 //#endregion
-export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesResponse, type ExtractedMachine, type GetMachineOptions, type GraphPatch, type InitOptions, type Inspector, type InspectorEvents, type MachineConfigOptions, type ManualActorOptions, type PlanSyncOptions, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectVisibility, type PullSyncResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type XStateTSOptions, type XStateVersion, contextSchemaToTSType, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, eventsSchemaToTSType, findStatelyPragmaAttachments, fromStudioMachine, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };
+export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesResponse, type ExtractedMachine, type GetMachineOptions, type GraphPatch, type InitOptions, type Inspector, type InspectorEvents, type MachineConfigOptions, type ManualActorOptions, type PlanSyncOptions, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type UpdateMachineInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type XStateTSOptions, type XStateVersion, contextSchemaToTSType, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, eventsSchemaToTSType, findStatelyPragmaAttachments, fromStudioMachine, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-C0eTgNNu.mjs";
+import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-C8UTS3Fa.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
 import { createStatelyInspector } from "./inspect.mjs";

package/dist/{inspect-BMIJcsFh.d.mts → inspect-Bg9FTvb3.d.mts}

@@ -1,4 +1,4 @@
-import { c as ExportFormatMap, o as ExportCallOptions, p as ProtocolMessage, r as EmbedEventMap, s as ExportFormat } from "./protocol-CDoCcaIP.mjs";
+import { c as ExportFormatMap, o as ExportCallOptions, p as ProtocolMessage, r as EmbedEventMap, s as ExportFormat } from "./protocol-DN4mH4jR.mjs";
 
 //#region src/transport.d.ts
 interface Transport {

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
-import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-CDoCcaIP.mjs";
-import { a as ManualActorOptions, i as InspectorEvents, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-BMIJcsFh.mjs";
+import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-DN4mH4jR.mjs";
+import { a as ManualActorOptions, i as InspectorEvents, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-Bg9FTvb3.mjs";
 export { AdoptedActor, CreateInspectorOptions, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, Inspector, InspectorEvents, ManualActorOptions, Transport, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,4 +1,4 @@
-import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-C0eTgNNu.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-C8UTS3Fa.mjs";
 
 //#region src/inspect.ts
 const defaultSerializeSnapshot = (snapshot) => ({

package/dist/{protocol-CDoCcaIP.d.mts → protocol-DN4mH4jR.d.mts}

@@ -60,9 +60,8 @@ interface ExportFormatMap {
     };
     result: string;
   };
-  json: {
+  'xstate-json': {
     options: {
-      simplifyArrays?: boolean;
       version?: 4 | 5;
     };
     result: Record<string, unknown>;

package/dist/studio.d.mts

@@ -75,6 +75,11 @@ interface CreateMachineFromTemplateInput {
   xstateVersion?: XStateVersion;
 }
 type CreateMachineInput<TDefinition = Record<string, unknown>> = CreateMachineFromDefinitionInput<TDefinition> | CreateMachineFromTemplateInput;
+interface UpdateMachineInput<TDefinition = Record<string, unknown>> {
+  id: string;
+  name?: string;
+  definition?: TDefinition;
+}
 interface StudioMachineRecord<TDefinition = Record<string, unknown>> {
   id: string;
   name: string;
@@ -99,6 +104,7 @@ interface StudioClient {
   machines: {
     create<TMachine = Record<string, unknown>>(input: CreateMachineInput<TMachine>): Promise<StudioMachineRecord<TMachine>>;
     createMany<TMachine = Record<string, unknown>>(input: CreateMachineInput<TMachine>): Promise<Array<StudioMachineRecord<TMachine>>>;
+    update<TMachine = Record<string, unknown>>(input: UpdateMachineInput<TMachine>): Promise<StudioMachineRecord<TMachine>>;
     get<TMachine = Record<string, unknown>>(machineId: string, options?: GetMachineOptions): Promise<TMachine>;
   };
   code: {
@@ -109,4 +115,4 @@ interface StudioClient {
 }
 declare function createStatelyClient(options?: StudioClientOptions): StudioClient;
 //#endregion
-export { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, VerifyApiKeyResponse, XStateVersion, createStatelyClient };
+export { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, UpdateMachineInput, VerifyApiKeyResponse, XStateVersion, createStatelyClient };

package/dist/studio.mjs

@@ -102,6 +102,13 @@ function createStatelyClient(options = {}) {
 			async createMany(input) {
 				return [await this.create(input)];
 			},
+			update(input) {
+				return request(`/machines/${encodeURIComponent(input.id)}`, {
+					method: "PATCH",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(input)
+				});
+			},
 			get(machineId, getOptions = {}) {
 				const search = new URLSearchParams();
 				if (getOptions.version) search.set("version", getOptions.version);

package/dist/sync.d.mts

@@ -52,8 +52,26 @@ interface PushSyncResult {
   machine: StudioMachineRecord<DigraphConfig>;
   outputPath?: string;
 }
+interface PushLocalMachineLinksResult {
+  sourcePath: string;
+  project: ProjectData;
+  created: Array<{
+    machineIndex: number;
+    machine: StudioMachineRecord<DigraphConfig>;
+  }>;
+  updated: Array<{
+    machineIndex: number;
+    machine: StudioMachineRecord<DigraphConfig>;
+  }>;
+  skipped: Array<{
+    machineIndex: number;
+    reason: string;
+  }>;
+  outputPath?: string;
+}
+declare function pushLocalMachineLinks(options: PushSyncOptions): Promise<PushLocalMachineLinksResult>;
 declare function planSync(options: PlanSyncOptions): Promise<SyncPlan>;
 declare function pullSync(options: PlanSyncOptions): Promise<PullSyncResult>;
 declare function pushSync(options: PushSyncOptions): Promise<PushSyncResult>;
 //#endregion
-export { PlanSyncOptions, PullSyncResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary, planSync, pullSync, pushSync };
+export { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary, planSync, pullSync, pushLocalMachineLinks, pushSync };

package/dist/sync.mjs

@@ -1,5 +1,5 @@
 import { createStatelyClient } from "./studio.mjs";
-import { d as upsertStatelyPragma, t as graphToXStateTS } from "./graphToXStateTS-Gzh0ZqbN.mjs";
+import { d as upsertStatelyPragma, l as findStatelyPragmaAttachments, t as graphToXStateTS, u as getStatelyPragma } from "./graphToXStateTS-Gzh0ZqbN.mjs";
 import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
 import { getDiff, isEmptyDiff } from "@statelyai/graph";
 import fs from "node:fs/promises";
@@ -186,6 +186,90 @@ function fromXStateConfig(config) {
 		data: {}
 	};
 }
+async function pushLocalMachineLinks(options) {
+	const client = options.client ?? createStatelyClient({
+		apiKey: options.apiKey,
+		baseUrl: options.baseUrl,
+		fetch: options.fetch
+	});
+	const sourcePath = path.resolve(options.cwd ?? process.cwd(), options.source);
+	const project = await resolvePushProject(client, sourcePath, options);
+	if (!project.projectVersionId) throw new Error("Resolved project is missing projectVersionId.");
+	const contents = await fs.readFile(sourcePath, "utf8");
+	const attachments = findStatelyPragmaAttachments(contents, sourcePath);
+	const extracted = await client.code.extractMachines(contents);
+	if (attachments.length === 0 || extracted.machines.length === 0) return {
+		sourcePath,
+		project,
+		created: [],
+		updated: [],
+		skipped: [{
+			machineIndex: 0,
+			reason: "No local machines were discovered in this file."
+		}]
+	};
+	if (attachments.length !== extracted.machines.length) return {
+		sourcePath,
+		project,
+		created: [],
+		updated: [],
+		skipped: [{
+			machineIndex: 0,
+			reason: "The local machine extractor did not align with the source attachments for this file."
+		}]
+	};
+	let nextContents = contents;
+	let outputPath;
+	const created = [];
+	const updated = [];
+	const skipped = [];
+	for (const [machineIndex, attachment] of attachments.entries()) {
+		const extractedMachine = extracted.machines[machineIndex];
+		if (!extractedMachine?.config) {
+			skipped.push({
+				machineIndex,
+				reason: "No extracted machine config was available for this source."
+			});
+			continue;
+		}
+		if (attachment.pragma?.id) {
+			const updatedMachine = await client.machines.update({
+				id: attachment.pragma.id,
+				definition: toStudioMachine(fromXStateConfig(extractedMachine.config))
+			});
+			updated.push({
+				machineIndex,
+				machine: updatedMachine
+			});
+			continue;
+		}
+		const machine = await client.machines.create({
+			projectVersionId: project.projectVersionId,
+			definition: toStudioMachine(fromXStateConfig(extractedMachine.config)),
+			xstateVersion: Math.max(5, options.xstateVersion ?? 5)
+		});
+		nextContents = upsertStatelyPragma(nextContents, machine.id, {
+			fileName: sourcePath,
+			machineIndex
+		});
+		created.push({
+			machineIndex,
+			machine
+		});
+	}
+	if (nextContents !== contents) {
+		await fs.writeFile(sourcePath, nextContents, "utf8");
+		outputPath = sourcePath;
+	}
+	return {
+		sourcePath,
+		project,
+		created,
+		updated,
+		skipped,
+		...outputPath ? { outputPath } : {}
+	};
+}
 async function resolveLocalFile(locator, options) {
 	const filePath = path.resolve(options.cwd ?? process.cwd(), locator);
 	const contents = await fs.readFile(filePath, "utf8");
@@ -350,12 +434,20 @@ async function pushSync(options) {
 	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
+	const existingMachineId = source.format === "xstate" ? getStatelyPragma(await fs.readFile(sourcePath, "utf8"), sourcePath)?.id : void 0;
+	let machine;
+	if (existingMachineId) machine = await client.machines.update({
+		id: existingMachineId,
+		definition: toStudioMachine(source.graph)
 	});
+	else {
+		if (!project.projectVersionId) throw new Error("Resolved project is missing projectVersionId.");
+		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");
@@ -374,4 +466,4 @@ async function pushSync(options) {
 }
 
 //#endregion
-export { planSync, pullSync, pushSync };
+export { planSync, pullSync, pushLocalMachineLinks, pushSync };

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

@@ -1,7 +1,7 @@
 //#region src/clientUtils.ts
 const jsonResultFormats = new Set([
 	"digraph",
-	"json",
+	"xstate-json",
 	"xgraph"
 ]);
 function createRequestId() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "license": "MIT",
   "bin": {
     "statelyai": "./dist/cli.mjs"
@@ -54,7 +54,9 @@
       "import": "./dist/assetStorage.mjs"
     },
     "./statelyai.schema.json": "./schemas/statelyai.schema.json",
-    "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json"
+    "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json",
+    "./xstate-json.schema.json": "./schemas/xstate-json.schema.json",
+    "./schemas/xstate-json.schema.json": "./schemas/xstate-json.schema.json"
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",

package/schemas/statelyai.schema.json

@@ -54,7 +54,7 @@
       "enum": [
         "auto",
         "xstate",
-        "json",
+        "xstate-json",
         "xgraph",
         "digraph",
         "mermaid",

package/schemas/xstate-json.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stately.ai/schemas/xstate-json.json",
+  "title": "XState JSON machine config",
+  "description": "Strict JSON subset of an XState machine config that can be passed to createMachine(config). Shorthand string forms are normalized to object and array forms.",
+  "$ref": "#/$defs/machineConfig",
+  "$defs": {
+    "jsonValue": {
+      "description": "Any JSON value.",
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "jsonObject": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+    },
+    "parameterizedObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "params": { "$ref": "#/$defs/jsonValue" }
+      }
+    },
+    "actionObject": {
+      "$ref": "#/$defs/parameterizedObject"
+    },
+    "guardObject": {
+      "$ref": "#/$defs/parameterizedObject"
+    },
+    "transitionObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "target": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "guard": { "$ref": "#/$defs/guardObject" },
+        "actions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "reenter": { "type": "boolean" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "description": { "type": "string" }
+      }
+    },
+    "transitionArray": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/transitionObject" }
+    },
+    "transitionsByEvent": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/transitionArray" }
+    },
+    "invokeObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["src"],
+      "properties": {
+        "id": { "type": "string" },
+        "systemId": { "type": "string" },
+        "src": { "type": "string", "minLength": 1 },
+        "input": { "$ref": "#/$defs/jsonValue" },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "onError": { "$ref": "#/$defs/transitionArray" },
+        "onSnapshot": { "$ref": "#/$defs/transitionArray" }
+      }
+    },
+    "stateNodeConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "enum": ["atomic", "compound", "parallel", "final", "history"]
+        },
+        "history": {
+          "anyOf": [
+            { "enum": ["shallow", "deep"] },
+            { "type": "boolean" }
+          ]
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stateNodeConfig" }
+        },
+        "invoke": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/invokeObject" }
+        },
+        "on": { "$ref": "#/$defs/transitionsByEvent" },
+        "entry": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "exit": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "after": { "$ref": "#/$defs/transitionsByEvent" },
+        "always": { "$ref": "#/$defs/transitionArray" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "output": { "$ref": "#/$defs/jsonValue" },
+        "order": { "type": "number" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "description": { "type": "string" },
+        "target": { "type": "string" },
+        "initial": { "type": "string" }
+      }
+    },
+    "machineConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "enum": ["atomic", "compound", "parallel", "final", "history"]
+        },
+        "history": {
+          "anyOf": [
+            { "enum": ["shallow", "deep"] },
+            { "type": "boolean" }
+          ]
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stateNodeConfig" }
+        },
+        "invoke": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/invokeObject" }
+        },
+        "on": { "$ref": "#/$defs/transitionsByEvent" },
+        "entry": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "exit": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "after": { "$ref": "#/$defs/transitionsByEvent" },
+        "always": { "$ref": "#/$defs/transitionArray" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "output": { "$ref": "#/$defs/jsonValue" },
+        "order": { "type": "number" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "description": { "type": "string" },
+        "target": { "type": "string" },
+        "initial": { "type": "string" },
+        "schemas": { "$ref": "#/$defs/jsonValue" },
+        "version": { "type": "string" },
+        "context": { "$ref": "#/$defs/jsonObject" },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxIterations": { "type": "number" }
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "id": "trafficLight",
+      "initial": "green",
+      "states": {
+        "green": {
+          "tags": ["go"],
+          "on": {
+            "TIMER": [
+              {
+                "target": ["yellow"],
+                "actions": [{ "type": "trackChange" }]
+              }
+            ]
+          }
+        },
+        "yellow": {
+          "on": {
+            "TIMER": [{ "target": ["red"] }]
+          }
+        },
+        "red": {
+          "type": "final"
+        }
+      }
+    }
+  ]
+}