statelyai 0.9.4 → 0.10.0

package/README.md

@@ -27,7 +27,7 @@ npm install --global statelyai
 | Goal                         | Command                                              | Writes                                                  |
 | ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
 | List local machines          | `statelyai scan`                                     | Nothing                                                 |
-| Edit one local file visually | `statelyai open <file>`                              | Local file, when you save in the editor                 |
+| Edit local machines visually | `statelyai open [file]`                              | Local source, when you save in the editor               |
 | Set up local discovery       | `statelyai init --local --scan`                      | Local `statelyai.json`                                  |
 | Set up project sync          | `statelyai init --scan`                              | Remote project and local `statelyai.json`               |
 | Inspect project machines     | `statelyai status`                                   | Nothing                                                 |
@@ -158,22 +158,24 @@ the credential so a later command can retry.
   "projectId": "project_123",
   "studioUrl": "https://stately.ai",
   "defaultXStateVersion": 5,
+  "sourceUpdateStrategy": "preserve",
   "include": ["src/**/*.ts"],
   "exclude": ["**/*.test.*", "**/*.spec.*"],
   "newMachinesDir": "src/machines"
 }
 ```
 
-| Field                  | Purpose                                                         |
-| ---------------------- | --------------------------------------------------------------- |
-| `$schema`              | Published JSON Schema URL.                                      |
-| `version`              | Config format version. Currently `1.0.0`.                       |
-| `projectId`            | Remote Studio project ID. Omitted for local-only projects.      |
-| `studioUrl`            | Studio API origin. Omitted for local-only projects.             |
-| `defaultXStateVersion` | XState version used when creating remote machines. Minimum `5`. |
-| `include`              | Source globs used by project-wide `push` and `pull`.            |
-| `exclude`              | Globs removed from discovery. Defaults to tests and specs.      |
-| `newMachinesDir`       | Destination for remote-only machines created by `pull`.         |
+| Field                  | Purpose                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `$schema`              | Published JSON Schema URL.                                              |
+| `version`              | Config format version. Currently `1.0.0`.                               |
+| `projectId`            | Remote Studio project ID. Omitted for local-only projects.              |
+| `studioUrl`            | Studio API origin. Omitted for local-only projects.                     |
+| `defaultXStateVersion` | XState version used when creating remote machines. Minimum `5`.         |
+| `sourceUpdateStrategy` | Visual writeback mode: `preserve` or `rewrite`. Defaults to `preserve`. |
+| `include`              | Source globs used by project-wide `push` and `pull`.                    |
+| `exclude`              | Globs removed from discovery. Defaults to tests and specs.              |
+| `newMachinesDir`       | Destination for remote-only machines created by `pull`.                 |
 
 Project-wide discovery identifies configured JavaScript and TypeScript files
 that import XState and call `createMachine(...)` or `.createMachine(...)`.
@@ -261,12 +263,21 @@ ID when present.
 
 ### `open`
 
-Start a local bridge and open one source file in the browser editor:
+Start a local bridge and open every machine in one source file as a workspace:
 
 ```bash
 statelyai open src/checkout.machine.ts
 ```
 
+Omit the file to discover every machine in the current worktree:
+
+```bash
+statelyai open
+```
+
+The workspace sidebar starts collapsed. Select a machine there without opening
+a separate browser tab.
+
 Saved file changes refresh the editor. Saving visual edits writes them back to
 the source file. Editor sync sends the opened file, its reachable relative
 imports, and ancestor package manifests; unrelated sibling files are excluded.
@@ -277,6 +288,13 @@ the editor keeps the current graph visible and offers retry, copy-details, and
 diagnostic-download actions. Use `--debug` to include the structured diagnostic
 in the CLI's redacted editor protocol log.
 
+Source updates default to `preserve`, which keeps existing formatting and
+comments with focused edits. Use `--source-update rewrite` or set
+`"sourceUpdateStrategy": "rewrite"` in `statelyai.json` to regenerate the
+selected machine from its semantic model. Rewrite may change formatting and
+comments inside that machine. When preserve cannot safely apply an edit, the
+editor offers `Rewrite machine` without discarding the visual changes.
+
 Flags:
 
 - `--editor-url <url>` selects the editor origin. Default:
@@ -285,6 +303,7 @@ Flags:
 - `--port <port>` selects a port. Default: a random available port.
 - `--no-open` starts the bridge without launching a browser.
 - `--debug` logs editor protocol messages with credentials redacted.
+- `--source-update <preserve|rewrite>` overrides the configured source update strategy.
 
 ### `diff`
 

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { S as run } from "./cli-DaH9lbVq.mjs";
+import { S as run } from "./cli-g_HqGi7Q.mjs";
 
 //#region src/bin.ts
 run();

package/dist/{cli-DaH9lbVq.mjs → cli-g_HqGi7Q.mjs}

@@ -11,13 +11,13 @@ import { promisify } from "node:util";
 import { Args, Command, Flags, flush, handle, run } from "@oclif/core";
 import * as http from "node:http";
 import * as ts from "typescript";
-import { EditorHostSession, StudioApiError, buildAuthorizeUrl, createPkcePair, createRemoteEditorSyncBackend, createStatelyClient, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, findStatelyPragmaAttachments, getStatelyPragma, refreshToken, registerOAuthClient } from "@statelyai/sdk";
+import { EditorHostWorkspaceSession, StudioApiError, buildAuthorizeUrl, createPkcePair, createRemoteEditorSyncBackend, createStatelyClient, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, findStatelyPragmaAttachments, getStatelyPragma, refreshToken, registerOAuthClient } from "@statelyai/sdk";
 import { WebSocket, WebSocketServer } from "ws";
 import os from "node:os";
 import { PullSourceReconciliationError, planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
 
 //#region src/version.ts
-const CLI_VERSION = "0.9.4";
+const CLI_VERSION = "0.10.0";
 
 //#endregion
 //#region src/cliHost.ts
@@ -57,27 +57,43 @@ function rawDataToBuffer(data) {
 }
 var RemoteEditorSession = class {
 	session;
+	workspaceWatcher;
 	constructor(options, sendMessage) {
 		this.options = options;
 		const send = (message) => {
 			this.log("send", message.type, message);
 			sendMessage(message);
 		};
-		this.session = new EditorHostSession({
-			source: {
-				rootUri: options.rootUri,
-				rootFileName: options.fileName,
-				rootDir: options.rootDir,
-				collectDocuments: (extraUris) => collectSourceDocuments({
-					rootFileName: options.fileName,
-					extraUris: [...extraUris ?? []]
-				}),
-				applyReplacements: async (replacements, rootUri) => {
-					await applyFileReplacements(replacements, rootUri);
-					return [...new Set(replacements.map((replacement) => replacement.uri ?? rootUri))];
-				},
-				watchSavedDocuments: (listener) => watchWorkspace(options.rootDir, listener)
-			},
+		const machines = options.machines ?? [{
+			id: `${options.rootUri}#0`,
+			fileName: options.fileName,
+			machineIndex: 0
+		}];
+		this.workspaceWatcher = createSharedWorkspaceWatcher(options.rootDir);
+		this.session = new EditorHostWorkspaceSession({
+			machines: machines.map((machine) => ({
+				id: machine.id,
+				name: machine.name,
+				source: {
+					rootUri: fileNameToUri(machine.fileName),
+					rootFileName: machine.fileName,
+					rootDir: options.rootDir,
+					machineIndex: machine.machineIndex,
+					collectDocuments: (extraUris) => collectSourceDocuments({
+						rootFileName: machine.fileName,
+						extraUris: [...extraUris ?? []]
+					}),
+					applyReplacements: async (replacements, rootUri) => {
+						await applyFileReplacements(replacements, rootUri);
+						return [...new Set(replacements.map((replacement) => replacement.uri ?? rootUri))];
+					},
+					watchSavedDocuments: (listener) => this.workspaceWatcher.subscribe(listener)
+				}
+			})),
+			currentMachineId: machines[0]?.id,
+			workspaceName: path$1.basename(options.rootDir),
+			projectWorkspaceOpen: false,
+			sourceUpdateStrategy: options.sourceUpdateStrategy ?? "preserve",
 			sync: createRemoteEditorSyncBackend({
 				editorUrl: options.editorUrl,
 				apiKey: options.apiKey,
@@ -98,6 +114,7 @@ var RemoteEditorSession = class {
 	}
 	dispose() {
 		this.session.dispose();
+		this.workspaceWatcher.dispose();
 	}
 	log(direction, type, payload) {
 		if (this.options.debug) console.error(`[${direction}] ${type}`, redactDebugPayload(payload) ?? "");
@@ -110,10 +127,18 @@ function redactDebugPayload(payload) {
 }
 async function openEditor(options) {
 	const fileName = path$1.resolve(options.fileName);
-	await fsPromises.access(fileName);
+	const machines = (options.machines ?? [{
+		id: `${fileNameToUri(fileName)}#0`,
+		fileName,
+		machineIndex: 0
+	}]).map((machine) => ({
+		...machine,
+		fileName: path$1.resolve(machine.fileName)
+	}));
+	await Promise.all([...new Set(machines.map((machine) => machine.fileName))].map((target) => fsPromises.access(target)));
 	await assertEditorHostAvailable(options.editorUrl);
 	const rootUri = fileNameToUri(fileName);
-	const rootDir = path$1.dirname(fileName);
+	const rootDir = path$1.resolve(options.rootDir ?? path$1.dirname(fileName));
 	let activeClient;
 	let session;
 	const server = http.createServer((request, response) => {
@@ -138,6 +163,7 @@ async function openEditor(options) {
 			session = new RemoteEditorSession({
 				...options,
 				fileName,
+				machines,
 				rootUri,
 				rootDir
 			}, (message) => activeClient?.send(message));
@@ -151,7 +177,7 @@ async function openEditor(options) {
 	const port = typeof address === "object" && address ? address.port : options.port;
 	const editorPageUrl = `http://${options.host}:${port}`;
 	console.log(`Stately visual editor: ${editorPageUrl}`);
-	console.log(`Editing ${fileName}`);
+	console.log(`Editing ${machines.length} machine${machines.length === 1 ? "" : "s"} in ${rootDir}`);
 	if (options.shouldOpen) openBrowser(editorPageUrl);
 	const shutdown = () => {
 		session?.dispose();
@@ -306,6 +332,22 @@ function watchWorkspace(rootDir, listener) {
 		timers.clear();
 	} };
 }
+function createSharedWorkspaceWatcher(rootDir) {
+	const listeners = /* @__PURE__ */ new Set();
+	const watcher = watchWorkspace(rootDir, (uri) => {
+		for (const listener of listeners) listener(uri);
+	});
+	return {
+		subscribe(listener) {
+			listeners.add(listener);
+			return { dispose: () => listeners.delete(listener) };
+		},
+		dispose() {
+			listeners.clear();
+			watcher.dispose();
+		}
+	};
+}
 function getCliWebviewContent(options) {
 	const baseUrl = normalizedBaseUrl(options.editorUrl);
 	const url = new URL(`${baseUrl}/embed`);
@@ -851,6 +893,7 @@ function normalizeProjectConfig(config) {
 		projectId: config.projectId ?? "",
 		studioUrl: config.studioUrl ?? "https://stately.ai",
 		defaultXStateVersion: Math.max(5, config.defaultXStateVersion ?? 5),
+		...config.sourceUpdateStrategy === "preserve" || config.sourceUpdateStrategy === "rewrite" ? { sourceUpdateStrategy: config.sourceUpdateStrategy } : {},
 		include: [...config.include ?? firstSource?.include ?? []],
 		exclude: config.exclude == null ? [...firstSource?.exclude ?? DEFAULT_SOURCE_EXCLUDES] : [...config.exclude],
 		...config.newMachinesDir ? { newMachinesDir: config.newMachinesDir } : {}
@@ -1730,7 +1773,7 @@ function inferDiscoveredMachineName(options) {
 	return `${path.basename(options.relativePath, path.extname(options.relativePath))}#${options.machineIndex + 1}`;
 }
 function discoverMachinesInSource(options) {
-	if (!looksLikeXStateMachineSource(options.source)) return [];
+	if (!hasXStateDependency(options.source)) return [];
 	return findStatelyPragmaAttachments(options.source, options.filePath).map((attachment, machineIndex) => ({
 		filePath: options.filePath,
 		...attachment.pragma?.id ? { id: attachment.pragma.id } : {},
@@ -1746,6 +1789,9 @@ function discoverMachinesInSource(options) {
 		relativePath: options.relativePath
 	}));
 }
+function hasXStateDependency(source) {
+	return /\bfrom\s*['"]xstate['"]/.test(source) || /\bimport\s*['"]xstate['"]/.test(source) || /\brequire\s*\(\s*['"]xstate['"]\s*\)/.test(source);
+}
 async function discoverMachinesInFiles(files) {
 	const machines = [];
 	for (const file of files) {
@@ -1781,11 +1827,6 @@ async function scanProjectSources(options) {
 	const cwd = path.resolve(options.cwd ?? process.cwd());
 	return suggestStatelySourceConfigs([...new Set((await scanProjectMachines({ cwd })).map((machine) => machine.relativePath))]);
 }
-function looksLikeXStateMachineSource(source) {
-	const hasXStateImport = /from\s+['"]xstate(?:\/[^'"]+)?['"]/.test(source) || /require\(\s*['"]xstate(?:\/[^'"]+)?['"]\s*\)/.test(source);
-	const hasMachineFactory = /\bcreateMachine\s*\(/.test(source) || /\.createMachine\s*\(/.test(source);
-	return hasXStateImport && hasMachineFactory;
-}
 async function classifyPushCandidates(files) {
 	const machineFiles = [];
 	const nonMachineFiles = [];
@@ -2324,11 +2365,11 @@ var PushCommand = class PushCommand extends Command {
 };
 var OpenCommand = class OpenCommand extends Command {
 	static enableJsonFlag = false;
-	static summary = "Open a local file in the Stately visual editor.";
-	static description = "Starts a local browser-backed editor session. Saved file changes update the visual editor, and saved visual edits are written back to the source file.";
+	static summary = "Open local machines in the Stately visual editor.";
+	static description = "Starts a local browser-backed workspace. Pass a file to open all its machines, or omit it to discover machines in the current worktree.";
 	static args = { file: Args.string({
-		required: true,
-		description: "Local source file to edit visually."
+		required: false,
+		description: "Local source file to edit visually. Defaults to the current worktree."
 	}) };
 	static flags = {
 		help: Flags.help({ char: "h" }),
@@ -2350,22 +2391,61 @@ var OpenCommand = class OpenCommand extends Command {
 		debug: Flags.boolean({
 			description: "Log editor protocol messages",
 			default: false
+		}),
+		"source-update": Flags.string({
+			description: "Source update strategy: preserve keeps formatting; rewrite regenerates the machine",
+			options: ["preserve", "rewrite"]
 		})
 	};
 	async run() {
 		const { args, flags } = await this.parse(OpenCommand);
 		const apiKey = (await resolveApiKey()).apiKey;
+		const cwd = process.cwd();
+		const discovered = args.file ? await discoverMachinesInFile(path.resolve(args.file)) : await scanProjectMachines({ cwd });
+		if (discovered.length === 0) throw new Error(args.file ? `No machines found in ${path.resolve(args.file)}.` : `No machines found in ${cwd}.`);
+		const rootDir = args.file ? path.dirname(path.resolve(args.file)) : cwd;
+		const machines = discovered.map((machine) => ({
+			id: `${pathToFileURL(machine.filePath).toString()}#${machine.machineIndex}`,
+			name: machine.name,
+			fileName: machine.filePath,
+			machineIndex: machine.machineIndex
+		}));
+		let configuredSourceUpdateStrategy;
+		try {
+			configuredSourceUpdateStrategy = (await readStatelyProjectConfig({ cwd })).config.sourceUpdateStrategy;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
 		await openEditor({
-			fileName: path.resolve(args.file),
+			fileName: machines[0].fileName,
+			machines,
+			rootDir,
 			editorUrl: flags["editor-url"] ?? getDefaultEditorUrl(),
 			host: flags.host,
 			port: flags.port,
 			shouldOpen: flags.open,
+			sourceUpdateStrategy: flags["source-update"] ?? configuredSourceUpdateStrategy ?? "preserve",
 			apiKey,
 			debug: flags.debug
 		});
 	}
 };
+async function discoverMachinesInFile(filePath) {
+	const source = await fsPromises.readFile(filePath, "utf8");
+	const discovered = discoverMachinesInSource({
+		filePath,
+		relativePath: path.basename(filePath),
+		source
+	});
+	if (discovered.length > 0) return discovered;
+	return [{
+		filePath,
+		line: 1,
+		machineIndex: 0,
+		name: path.basename(filePath),
+		relativePath: path.basename(filePath)
+	}];
+}
 var InitCommand = class InitCommand extends Command {
 	static enableJsonFlag = false;
 	static summary = "Create a local or Studio-connected statelyai.json.";

package/dist/index.d.mts

@@ -36,6 +36,7 @@ interface StatelyProjectConfig {
   projectId: string;
   studioUrl: string;
   defaultXStateVersion: number;
+  sourceUpdateStrategy?: 'preserve' | 'rewrite';
   include: string[];
   exclude?: string[];
   newMachinesDir?: string;
@@ -303,7 +304,7 @@ declare class OpenCommand extends Command {
   static summary: string;
   static description: string;
   static args: {
-    file: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    file: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
   };
   static flags: {
     help: _oclif_core_interfaces0.BooleanFlag<void>;
@@ -312,6 +313,7 @@ declare class OpenCommand extends Command {
     port: _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
     open: _oclif_core_interfaces0.BooleanFlag<boolean>;
     debug: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    'source-update': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { C as scanProjectMachines, S as run, T as createStatelyProjectConfig, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectSources, x as resolveProjectStatus, y as resolveConfiguredPullTargets } from "./cli-DaH9lbVq.mjs";
+import { C as scanProjectMachines, S as run, T as createStatelyProjectConfig, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectSources, x as resolveProjectStatus, y as resolveConfiguredPullTargets } from "./cli-g_HqGi7Q.mjs";
 
 export { COMMANDS, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveProjectStatus, run, scanProjectMachines, scanProjectSources };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statelyai",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Command-line tools for Stately",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
     "@oclif/core": "^4.10.3",
     "typescript": "^5.9.3",
     "ws": "^8.21.0",
-    "@statelyai/sdk": "0.29.1"
+    "@statelyai/sdk": "0.31.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",