statelyai 0.8.23 → 0.9.0

package/README.md

@@ -88,9 +88,14 @@ statelyai pull
 ```
 
 `push` creates remote machines for unlinked source machines, updates already
-linked machines, and writes returned IDs into source comments. `pull` updates
-linked files. If `newMachinesDir` is configured, it also creates local files
-for machines that exist only in the Studio project.
+linked machines, and writes returned IDs into source comments. Updating a
+linked machine preserves Studio layout, colors, and annotations for unchanged
+states while applying local structural changes. New states use default layout.
+`pull` updates linked files. If `newMachinesDir` is configured, it also creates
+local files for machines that exist only in the Studio project.
+Push re-reads and retries when it observes a concurrent Studio edit. Registry
+updates do not yet expose an atomic revision precondition, so avoid editing the
+same machine in Studio during a push.
 
 ## Authentication
 
@@ -296,9 +301,10 @@ Locators may be:
 - a Studio machine ID
 - a Studio machine URL
 
-`--fail-on-changes` exits with status `1` when the normalized graphs differ.
-Use `--base-url` for remote IDs at another Studio origin. `plan` remains a
-hidden compatibility alias for `diff`.
+`--fail-on-changes` exits with status `1` when machine semantics differ.
+Entity IDs and presentation-only layout or color fields do not count as
+changes. Use `--base-url` for remote IDs at another Studio origin. `plan`
+remains a hidden compatibility alias for `diff`.
 
 ### `push`
 
@@ -323,6 +329,13 @@ statelyai push --dry-run
 `--dry-run` does not create or update machines, write `@statelyai` IDs, or
 migrate legacy configuration.
 
+For linked machines, `push` reads the current remote definition before updating
+it. Local source remains authoritative for structure; Studio presentation for
+unchanged states and transitions is preserved.
+Push re-reads before writing and retries if it observes a remote change.
+Registry updates do not yet expose an atomic revision precondition, so avoid
+editing the same machine in Studio during a push.
+
 Flags: `--config <path>`, `--base-url <url>`, `--dry-run`.
 
 ### `pull`
@@ -347,9 +360,17 @@ statelyai pull machine_123 src/checkout.machine.ts
 
 New targets support JavaScript/TypeScript, `.digraph.json`, and `.graph.json`.
 For existing JSON targets, the current file shape determines the output format.
+Existing JavaScript and TypeScript targets are updated through surgical graph
+patches so surrounding comments, imports, helpers, and implementation bodies
+survive. New source files and JSON targets are generated as complete files.
 
 Project-wide pull skips linked files with uncommitted Git changes. Pass
-`--force` to overwrite them. Remote-only machines are skipped until
+`--force` to overwrite them. If an existing source file cannot be updated
+safely, pull leaves it unchanged and exits nonzero; `--force` explicitly allows
+complete regeneration, which discards comments, imports, and helper code around
+the machine. `--force` enables both behaviors together, so use it only when full
+regeneration is acceptable. Every linked machine in a multi-machine source file
+is pulled independently. Remote-only machines are skipped until
 `newMachinesDir` is set.
 
 Flags: `--config <path>`, `--base-url <url>`, `--force`.

package/dist/bin.mjs

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

package/dist/{cli-BiA4S5aG.mjs → cli-uNjqtpTz.mjs}

@@ -14,10 +14,10 @@ import * as ts from "typescript";
 import { EditorHostSession, 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 { planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
+import { PullSourceReconciliationError, planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
 
 //#region src/version.ts
-const CLI_VERSION = "0.8.23";
+const CLI_VERSION = "0.9.0";
 
 //#endregion
 //#region src/cliHost.ts
@@ -1601,11 +1601,12 @@ async function discoverLinkedPullTargets(files) {
 	const linkedTargets = [];
 	for (const file of files) {
 		if (!supportsMachineDiscovery(file)) continue;
-		const pragma = getStatelyPragma(await fsPromises.readFile(file.filePath, "utf8"), file.filePath);
-		if (!pragma?.id) continue;
-		linkedTargets.push({
-			file,
-			machineId: pragma.id
+		findStatelyPragmaAttachments(await fsPromises.readFile(file.filePath, "utf8"), file.filePath).forEach((attachment, machineIndex) => {
+			if (attachment.pragma?.id) linkedTargets.push({
+				file,
+				machineId: attachment.pragma.id,
+				machineIndex
+			});
 		});
 	}
 	return linkedTargets;
@@ -2125,9 +2126,14 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 			this.log(colorize(`Processing ${linkedTargets.length} ${pluralize(linkedTargets.length, "linked file")}${remoteOnlyTargets.length > 0 ? ` and ${remoteOnlyTargets.length} ${pluralize(remoteOnlyTargets.length, "new remote machine")}` : ""}...`, ANSI_CYAN));
 			const pulled = [];
 			const created = [];
+			let hadSourceReconciliationFailure = false;
+			const dirtyLinkedFiles = /* @__PURE__ */ new Map();
+			if (!flags.force) await Promise.all([...new Set(linkedTargets.map((target) => target.file.filePath))].map(async (filePath) => {
+				dirtyLinkedFiles.set(filePath, await isFileGitDirty(filePath));
+			}));
 			for (const linkedTarget of linkedTargets) {
 				const targetPath = linkedTarget.file.filePath;
-				if (!flags.force && await isFileGitDirty(targetPath)) {
+				if (!flags.force && dirtyLinkedFiles.get(targetPath)) {
 					skipped.push(`${linkedTarget.file.relativePath}: local git changes detected (pass --force to overwrite)`);
 					continue;
 				}
@@ -2137,10 +2143,13 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 						source: linkedTarget.machineId,
 						target: targetPath,
 						apiKey,
-						baseUrl: resolveApiBaseUrl(flags["base-url"] ?? config.studioUrl)
+						baseUrl: resolveApiBaseUrl(flags["base-url"] ?? config.studioUrl),
+						force: flags.force,
+						machineIndex: linkedTarget.machineIndex
 					});
 					pulled.push(`${linkedTarget.file.relativePath}: ${formatSecondaryText(result.source.locator)}`);
 				} catch (error) {
+					if (error instanceof PullSourceReconciliationError) hadSourceReconciliationFailure = true;
 					skipped.push(`${linkedTarget.file.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
 				}
 			}
@@ -2152,16 +2161,19 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 						source: remoteTarget.machineId,
 						target: remoteTarget.filePath,
 						apiKey,
-						baseUrl: resolveApiBaseUrl(flags["base-url"] ?? config.studioUrl)
+						baseUrl: resolveApiBaseUrl(flags["base-url"] ?? config.studioUrl),
+						force: flags.force
 					});
 					created.push(`${remoteTarget.relativePath}: ${formatSecondaryText(result.source.locator)}`);
 				} catch (error) {
+					if (error instanceof PullSourceReconciliationError) hadSourceReconciliationFailure = true;
 					skipped.push(`${remoteTarget.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
 				}
 			}
 			if (pulled.length > 0) this.log(`${formatSectionLabel("Pulled:", "success")}\n${pulled.join("\n")}`);
 			if (created.length > 0) this.log(`${formatSectionLabel("Created:", "success")}\n${created.join("\n")}`);
 			if (skipped.length > 0) this.log(`${formatSectionLabel("Skipped:", "warning")}\n${skipped.join("\n")}`);
+			if (hadSourceReconciliationFailure) this.exit(1);
 			return;
 		}
 		const localCandidate = path.resolve(process.cwd(), args.source);
@@ -2180,7 +2192,8 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 			source,
 			target,
 			apiKey,
-			baseUrl: resolveApiBaseUrl(flags["base-url"] ?? getDefaultBaseUrl())
+			baseUrl: resolveApiBaseUrl(flags["base-url"] ?? getDefaultBaseUrl()),
+			force: flags.force
 		});
 		this.log(`${formatSectionLabel("Pulled:", "success")} ${formatSecondaryText(result.source.locator)} -> ${result.outputPath}\nTarget: ${result.target.kind} (${result.target.format})`);
 	}

package/dist/index.d.mts

@@ -84,6 +84,7 @@ interface DiscoveredMachine {
 interface LinkedPullTarget {
   file: DiscoveredSourceFile;
   machineId: string;
+  machineIndex: number;
 }
 interface RemoteProjectMachineTarget {
   machineId: string;

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-BiA4S5aG.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-uNjqtpTz.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.8.23",
+  "version": "0.9.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.26.3"
+    "@statelyai/sdk": "0.27.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",