statelyai 0.4.0 → 0.5.0

package/README.md

@@ -36,7 +36,8 @@ That writes a `statelyai.json` like:
   "studioUrl": "https://stately.ai",
   "defaultXStateVersion": 5,
   "include": ["src/**/*.ts"],
-  "exclude": ["**/*.test.*", "**/*.spec.*"]
+  "exclude": ["**/*.test.*", "**/*.spec.*"],
+  "newMachineDir": "src"
 }
 ```
 
@@ -52,13 +53,15 @@ Preview what `push` would do without updating Studio or local files:
 statelyai push --dry-run
 ```
 
-6. Pull remote changes back into linked local files:
+If a saved `// @statelyai id=...` points to a deleted or inaccessible remote machine, `push` will prompt to relink the file as a new remote machine and replace the local id.
+
+6. Pull remote changes back into linked local files and create new local files for remote-only project machines when `newMachineDir` is configured:
 
 ```bash
 statelyai pull
 ```
 
-`pull` skips locally modified files unless you pass `--force`.
+`pull` skips locally modified linked files unless you pass `--force`. New remote-only machines are written as `<machine-name>.machine.ts` inside `newMachineDir`.
 
 Run it without installing it globally:
 

package/dist/bin.mjs

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

package/dist/{cli-DvtWVXpM.mjs → cli-1Nrsh5Xl.mjs}

@@ -12,7 +12,7 @@ import * as crypto from "node:crypto";
 import * as http from "node:http";
 import * as https from "node:https";
 import os from "node:os";
-import { createStatelyClient, getStatelyPragma } from "@statelyai/sdk";
+import { StudioApiError, createStatelyClient, getStatelyPragma } from "@statelyai/sdk";
 import { planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
 
 //#region src/cliHost.ts
@@ -975,7 +975,8 @@ function normalizeProjectConfig(config) {
 		studioUrl: config.studioUrl ?? "https://stately.ai",
 		defaultXStateVersion: Math.max(5, config.defaultXStateVersion ?? 5),
 		include: [...config.include ?? firstSource?.include ?? []],
-		exclude: config.exclude == null ? [...firstSource?.exclude ?? DEFAULT_SOURCE_EXCLUDES] : [...config.exclude]
+		exclude: config.exclude == null ? [...firstSource?.exclude ?? DEFAULT_SOURCE_EXCLUDES] : [...config.exclude],
+		...config.newMachineDir ? { newMachineDir: config.newMachineDir } : {}
 	};
 }
 async function readStatelyProjectConfig(options = {}) {
@@ -1060,6 +1061,9 @@ function matchesGlob(relativePath, pattern) {
 function matchesAny(patterns, relativePath) {
 	return (patterns ?? []).some((pattern) => matchesGlob(relativePath, pattern));
 }
+function isTrackedByStatelyProjectConfig(config, relativePath) {
+	return matchesAny(config.include, relativePath) && !matchesAny(config.exclude ?? DEFAULT_SOURCE_EXCLUDES, relativePath);
+}
 async function discoverCodeSourceFiles(options = {}) {
 	const rootDir = path.resolve(options.cwd ?? process.cwd());
 	return (await filterGitIgnoredPaths(rootDir, await walkFiles(rootDir))).filter((relativePath) => isCodeSourceFile(relativePath)).filter((relativePath) => !matchesAny(DEFAULT_SOURCE_EXCLUDES, relativePath)).sort((left, right) => left.localeCompare(right));
@@ -1157,6 +1161,7 @@ async function discoverStatelySourceFiles(options = {}) {
 //#region src/cli.ts
 const execFileAsync = promisify(execFile);
 const STATELY_API_KEY_SETTINGS_URL = "https://stately.ai/registry/user/my-settings?tab=API+Key";
+const DEFAULT_NEW_MACHINE_FILE_SUFFIX = ".machine.ts";
 function loadLocalEnv() {
 	if (typeof process.loadEnvFile !== "function") return;
 	const cwdEnvPath = path.join(process.cwd(), ".env.local");
@@ -1310,6 +1315,9 @@ function normalizeApiKey(value) {
 function pluralize(count, singular, plural = `${singular}s`) {
 	return count === 1 ? singular : plural;
 }
+function toMachineFileStem(machineName) {
+	return machineName.trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "machine";
+}
 function getMissingApiKeyMessage() {
 	return `No API key configured. Use \`statelyai login\`, set \`STATELY_API_KEY\`, or pass \`--api-key\`.\nGet or create an API key at ${STATELY_API_KEY_SETTINGS_URL}`;
 }
@@ -1321,6 +1329,22 @@ function buildMachineEditorUrl(studioUrl, projectId, machineId) {
 	url.searchParams.set("machineId", machineId);
 	return url.toString();
 }
+function inferNewMachineDirFromSuggestions(suggestions) {
+	if (suggestions.length !== 1) return;
+	const include = suggestions[0]?.include[0];
+	if (!include) return;
+	const globIndex = include.indexOf("**/");
+	if (globIndex >= 0) return include.slice(0, globIndex).replace(/\/$/, "") || void 0;
+	const directory = path.posix.dirname(include);
+	return directory === "." ? void 0 : directory;
+}
+function isRelinkableLinkedMachineError(error) {
+	return error instanceof StudioApiError && (error.status === 403 || error.status === 404);
+}
+async function fileHasLinkedMachineId(filePath) {
+	const contents = await fsPromises.readFile(filePath, "utf8");
+	return Boolean(getStatelyPragma(contents, filePath)?.id);
+}
 async function fileExists(filePath) {
 	try {
 		await fsPromises.access(filePath);
@@ -1393,6 +1417,35 @@ async function discoverLinkedPullTargets(files) {
 	}
 	return linkedTargets;
 }
+async function discoverRemoteProjectMachineTargets(options) {
+	const newMachineDir = options.config.newMachineDir?.trim();
+	if (!newMachineDir) return [];
+	const targets = [];
+	for (const machine of options.project.machines) {
+		if (options.linkedMachineIds.has(machine.machineId)) continue;
+		const baseDirectory = path.join(options.rootDir, newMachineDir);
+		const stem = toMachineFileStem(machine.name);
+		let candidateFileName = `${stem}${DEFAULT_NEW_MACHINE_FILE_SUFFIX}`;
+		let attempt = 2;
+		for (;;) {
+			const filePath = path.join(baseDirectory, candidateFileName);
+			const relativePath = path.relative(options.rootDir, filePath).replace(/\\/g, "/");
+			if (!isTrackedByStatelyProjectConfig(options.config, relativePath)) throw new Error(`Generated path ${relativePath} for remote machine ${machine.name} is not covered by include/exclude globs.`);
+			if (!await fileExists(filePath)) {
+				targets.push({
+					machineId: machine.machineId,
+					machineName: machine.name,
+					filePath,
+					relativePath
+				});
+				break;
+			}
+			candidateFileName = `${stem}-${attempt}${DEFAULT_NEW_MACHINE_FILE_SUFFIX}`;
+			attempt += 1;
+		}
+	}
+	return targets;
+}
 async function initProject(options) {
 	const cwd = path.resolve(options.cwd ?? process.cwd());
 	const studioUrl = getResolvedStudioUrl(options.baseUrl);
@@ -1602,19 +1655,38 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 		if (!args.source) {
 			if (!apiKey) this.error(getMissingApiKeyMessage());
 			this.log("Resolving configured project and linked source files...");
-			const { files, config } = await resolveConfiguredProject({
+			const { files, config, configPath } = await resolveConfiguredProject({
 				apiKey,
 				baseUrl: flags["base-url"],
 				configPath: flags.config
 			});
 			const linkedTargets = await discoverLinkedPullTargets(files);
-			if (linkedTargets.length === 0) {
-				this.log("No linked local machine files were discovered.");
+			const linkedMachineIds = new Set(linkedTargets.map((linkedTarget) => linkedTarget.machineId));
+			const project = await client.projects.get(config.projectId);
+			const skipped = [];
+			let remoteOnlyTargets = [];
+			try {
+				remoteOnlyTargets = await discoverRemoteProjectMachineTargets({
+					rootDir: path.dirname(configPath),
+					config,
+					project,
+					linkedMachineIds
+				});
+			} catch (error) {
+				skipped.push(error instanceof Error ? error.message : String(error));
+			}
+			if (linkedTargets.length === 0 && remoteOnlyTargets.length === 0) {
+				if (project.machines.length > 0 && !config.newMachineDir) {
+					this.log("No linked local machine files were discovered, and statelyai.json does not set newMachineDir for importing remote-only machines.");
+					return;
+				}
+				this.log("No linked local machine files or remote-only project machines were discovered.");
 				return;
 			}
-			this.log(`Processing ${linkedTargets.length} ${pluralize(linkedTargets.length, "linked file")}...`);
+			if (project.machines.length > linkedTargets.length && !config.newMachineDir) this.log("Remote-only project machines were found, but statelyai.json does not set newMachineDir, so they will be skipped.");
+			this.log(`Processing ${linkedTargets.length} ${pluralize(linkedTargets.length, "linked file")}${remoteOnlyTargets.length > 0 ? ` and ${remoteOnlyTargets.length} ${pluralize(remoteOnlyTargets.length, "new remote machine")}` : ""}...`);
 			const pulled = [];
-			const skipped = [];
+			const created = [];
 			for (const linkedTarget of linkedTargets) {
 				const targetPath = linkedTarget.file.filePath;
 				if (!flags.force && await isFileGitDirty(targetPath)) {
@@ -1634,7 +1706,23 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 					skipped.push(`${linkedTarget.file.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
 				}
 			}
+			for (const remoteTarget of remoteOnlyTargets) {
+				this.log(`Pulling new remote machine ${remoteTarget.machineName} into ${remoteTarget.relativePath}...`);
+				try {
+					await fsPromises.mkdir(path.dirname(remoteTarget.filePath), { recursive: true });
+					const result = await pullSync({
+						source: remoteTarget.machineId,
+						target: remoteTarget.filePath,
+						apiKey,
+						baseUrl: flags["base-url"] ?? config.studioUrl
+					});
+					created.push(`${remoteTarget.relativePath}: ${result.source.locator}`);
+				} catch (error) {
+					skipped.push(`${remoteTarget.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}
 			if (pulled.length > 0) this.log(`Pulled:\n${pulled.join("\n")}`);
+			if (created.length > 0) this.log(`Created:\n${created.join("\n")}`);
 			if (skipped.length > 0) this.log(`Skipped:\n${skipped.join("\n")}`);
 			return;
 		}
@@ -1740,14 +1828,38 @@ var PushCommand = class PushCommand extends Command {
 				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)
-			});
+			let result;
+			try {
+				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)
+				});
+			} catch (error) {
+				if (isRelinkableLinkedMachineError(error) && await fileHasLinkedMachineId(file.filePath)) {
+					if (!process.stdin.isTTY || !process.stdout.isTTY) {
+						skipped.push(`${file.relativePath}: linked remote machine is missing or inaccessible. Re-run interactively to relink it as a new machine.`);
+						continue;
+					}
+					if (!await promptYesNo(`Linked remote machine for ${file.relativePath} is missing or inaccessible. Push it as a new machine and replace the local @statelyai id?`, true)) {
+						skipped.push(`${file.relativePath}: linked remote machine is missing or inaccessible.`);
+						continue;
+					}
+					this.log(`Relinking ${file.relativePath} as a new remote machine...`);
+					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),
+						relink: true
+					});
+				} else throw error;
+			}
 			if (result.created.length > 0) linked.push(`${file.relativePath}: ${result.created.map(({ machineIndex, machine }) => `${machine.id} [${machineIndex}] ${buildMachineEditorUrl(config.studioUrl, config.projectId, machine.id)}`).join(", ")}`);
 			if (result.updated.length > 0) refreshed.push(`${file.relativePath}: ${result.updated.map(({ machineIndex, machine }) => `${machine.id} [${machineIndex}] ${buildMachineEditorUrl(config.studioUrl, config.projectId, machine.id)}`).join(", ")}`);
 			for (const entry of result.skipped) skipped.push(`${file.relativePath} [${entry.machineIndex}]: ${entry.reason}`);
@@ -1858,13 +1970,15 @@ var InitCommand = class InitCommand extends Command {
 			this.log(initMessage);
 			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 inferredNewMachineDir = inferNewMachineDirFromSuggestions(suggestions);
 				const nextConfig = {
 					...result.config,
 					include: suggestions.flatMap((suggestion) => suggestion.include),
-					exclude: [...new Set(suggestions.flatMap((suggestion) => suggestion.exclude ?? []))]
+					exclude: [...new Set(suggestions.flatMap((suggestion) => suggestion.exclude ?? []))],
+					...inferredNewMachineDir ? { newMachineDir: inferredNewMachineDir } : {}
 				};
 				await fsPromises.writeFile(result.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
-				this.log("Saved scanned source globs to statelyai.json.");
+				this.log(inferredNewMachineDir ? `Saved scanned source globs to statelyai.json.\nNew remote machines will be created under ${inferredNewMachineDir}/ by default.` : "Saved scanned source globs to statelyai.json.");
 			} else this.log("Left statelyai.json unchanged. Edit it before running statelyai push.");
 			return;
 		}
@@ -1960,4 +2074,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run$1();
 
 //#endregion
-export { getEnvApiKey as a, isFileGitDirty as c, scanProjectSources as d, createStatelyProjectConfig as f, formatPlanSummary as i, resolveApiKey as l, classifyPushCandidates as n, inferInitProjectName as o, discoverLinkedPullTargets as r, initProject as s, COMMANDS as t, run$1 as u };
+export { formatPlanSummary as a, initProject as c, run$1 as d, scanProjectSources as f, discoverRemoteProjectMachineTargets as i, isFileGitDirty as l, classifyPushCandidates as n, getEnvApiKey as o, createStatelyProjectConfig as p, discoverLinkedPullTargets as r, inferInitProjectName as s, COMMANDS as t, resolveApiKey as u };

package/dist/index.d.mts

@@ -18,6 +18,7 @@ interface StatelyProjectConfig {
   defaultXStateVersion: number;
   include: string[];
   exclude?: string[];
+  newMachineDir?: string;
 }
 interface DiscoveredSourceFile {
   filePath: string;
@@ -55,6 +56,12 @@ interface LinkedPullTarget {
   file: DiscoveredSourceFile;
   machineId: string;
 }
+interface RemoteProjectMachineTarget {
+  machineId: string;
+  machineName: string;
+  filePath: string;
+  relativePath: string;
+}
 interface PushCandidateClassification {
   machineFiles: DiscoveredSourceFile[];
   nonMachineFiles: DiscoveredSourceFile[];
@@ -76,6 +83,12 @@ declare function resolveApiKey(explicitApiKey?: string): Promise<ApiKeyResolutio
 declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string;
 declare function isFileGitDirty(filePath: string): Promise<boolean>;
 declare function discoverLinkedPullTargets(files: DiscoveredSourceFile[]): Promise<LinkedPullTarget[]>;
+declare function discoverRemoteProjectMachineTargets(options: {
+  rootDir: string;
+  config: StatelyProjectConfig;
+  project: ProjectData;
+  linkedMachineIds: Set<string>;
+}): Promise<RemoteProjectMachineTarget[]>;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
 declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<Array<Pick<StatelyProjectConfig, 'include' | 'exclude'>>>;
 declare function classifyPushCandidates(files: DiscoveredSourceFile[]): Promise<PushCandidateClassification>;
@@ -227,4 +240,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: any, entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, PushCandidateClassification, ScanProjectSourcesOptions, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, PushCandidateClassification, RemoteProjectMachineTarget, ScanProjectSourcesOptions, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverRemoteProjectMachineTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as getEnvApiKey, c as isFileGitDirty, d as scanProjectSources, f as createStatelyProjectConfig, i as formatPlanSummary, l as resolveApiKey, n as classifyPushCandidates, o as inferInitProjectName, r as discoverLinkedPullTargets, s as initProject, t as COMMANDS, u as run } from "./cli-DvtWVXpM.mjs";
+import { a as formatPlanSummary, c as initProject, d as run, f as scanProjectSources, i as discoverRemoteProjectMachineTargets, l as isFileGitDirty, n as classifyPushCandidates, o as getEnvApiKey, p as createStatelyProjectConfig, r as discoverLinkedPullTargets, s as inferInitProjectName, t as COMMANDS, u as resolveApiKey } from "./cli-1Nrsh5Xl.mjs";
 
-export { COMMANDS, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };
+export { COMMANDS, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverRemoteProjectMachineTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statelyai",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Command-line tools for Stately",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",
-    "@statelyai/sdk": "0.9.0"
+    "@statelyai/sdk": "0.10.0"
   },
   "devDependencies": {
     "tsdown": "0.21.0-beta.2",