statelyai 0.3.7 → 0.4.0

package/README.md

@@ -4,6 +4,7 @@ CLI implementation for Stately.
 
 This package contains the `statelyai` command implementation.
 
+<!-- happy-path CLI usage and statelyai.json shape derived from packages/cli/src/cli.ts#COMMANDS and packages/cli/src/projectConfig.ts -->
 ## Happy Path
 
 1. Get an API key from [Stately API Key settings](https://stately.ai/registry/user/my-settings?tab=API+Key).
@@ -25,18 +26,40 @@ statelyai init
 statelyai init --scan
 ```
 
+That writes a `statelyai.json` like:
+
+```json
+{
+  "$schema": "https://stately.ai/schemas/statelyai.json",
+  "version": "1.0.0",
+  "projectId": "project_123",
+  "studioUrl": "https://stately.ai",
+  "defaultXStateVersion": 5,
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.*", "**/*.spec.*"]
+}
+```
+
 5. Push local machines:
 
 ```bash
 statelyai push
 ```
 
+Preview what `push` would do without updating Studio or local files:
+
+```bash
+statelyai push --dry-run
+```
+
 6. Pull remote changes back into linked local files:
 
 ```bash
 statelyai pull
 ```
 
+`pull` skips locally modified files unless you pass `--force`.
+
 Run it without installing it globally:
 
 ```bash

package/dist/bin.mjs

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

package/dist/{cli-B9CRx5db.mjs → cli-DvtWVXpM.mjs}

@@ -945,6 +945,15 @@ const CODE_SOURCE_EXTENSIONS = new Set([
 	".cjs"
 ]);
 const execFileAsync$1 = promisify(execFile);
+const ALWAYS_IGNORED_DIRECTORIES = new Set([
+	".git",
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	".next"
+]);
 function createStatelyProjectConfig(options) {
 	const defaultXStateVersion = options.defaultXStateVersion ?? 5;
 	return {
@@ -953,21 +962,20 @@ function createStatelyProjectConfig(options) {
 		projectId: options.projectId,
 		studioUrl: options.studioUrl,
 		defaultXStateVersion,
-		sources: []
-	};
-}
-function normalizeSourceConfig(source) {
-	return {
-		include: [...source.include ?? []],
-		exclude: source.exclude == null ? [...DEFAULT_SOURCE_EXCLUDES] : [...source.exclude],
-		format: source.format ?? "xstate",
-		...source.xstateVersion == null ? {} : { xstateVersion: source.xstateVersion }
+		include: [],
+		exclude: [...DEFAULT_SOURCE_EXCLUDES]
 	};
 }
 function normalizeProjectConfig(config) {
+	const firstSource = config.sources?.[0];
 	return {
-		...config,
-		sources: (config.sources ?? []).map((source) => normalizeSourceConfig(source))
+		$schema: config.$schema ?? STATELY_CONFIG_SCHEMA_URL,
+		version: config.version ?? STATELY_CONFIG_VERSION,
+		projectId: config.projectId ?? "",
+		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]
 	};
 }
 async function readStatelyProjectConfig(options = {}) {
@@ -984,7 +992,7 @@ async function walkFiles(rootDir, currentDir = rootDir) {
 	const entries = await fsPromises.readdir(currentDir, { withFileTypes: true });
 	const files = [];
 	for (const entry of entries) {
-		if (entry.name === ".git") continue;
+		if (ALWAYS_IGNORED_DIRECTORIES.has(entry.name)) continue;
 		const absolutePath = path.join(currentDir, entry.name);
 		if (entry.isDirectory()) {
 			files.push(...await walkFiles(rootDir, absolutePath));
@@ -996,21 +1004,14 @@ async function walkFiles(rootDir, currentDir = rootDir) {
 	return files;
 }
 async function filterGitIgnoredPaths(rootDir, relativeFiles) {
+	if (relativeFiles.length === 0) return relativeFiles;
 	try {
-		const { stdout } = await execFileAsync$1("git", [
-			"ls-files",
-			"--others",
-			"--ignored",
-			"--exclude-standard",
-			"--directory"
-		], { cwd: rootDir });
+		const { stdout } = await execFileAsync$1("git", ["check-ignore", ...relativeFiles], { cwd: rootDir });
 		const ignoredEntries = stdout.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean);
 		if (ignoredEntries.length === 0) return relativeFiles;
+		const ignoredPaths = new Set(ignoredEntries);
 		return relativeFiles.filter((relativePath) => {
-			return !ignoredEntries.some((ignoredEntry) => {
-				if (ignoredEntry.endsWith("/")) return relativePath.startsWith(ignoredEntry);
-				return relativePath === ignoredEntry;
-			});
+			return !ignoredPaths.has(relativePath);
 		});
 	} catch {
 		return relativeFiles;
@@ -1063,30 +1064,51 @@ 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));
 }
-function createSuggestedSource(include) {
+function createSuggestedConfig(include) {
 	return {
 		include: [include],
-		exclude: [...DEFAULT_SOURCE_EXCLUDES],
-		format: "xstate",
-		xstateVersion: 5
+		exclude: [...DEFAULT_SOURCE_EXCLUDES]
 	};
 }
-function suggestStatelySourceConfigs(relativePaths, defaultXStateVersion = 5) {
+function toExtensionToken(extname) {
+	return extname.startsWith(".") ? extname.slice(1) : extname;
+}
+function formatExtensionPattern(extnames) {
+	const unique = [...new Set(extnames.map(toExtensionToken))].sort();
+	if (unique.length === 1) return `.${unique[0]}`;
+	return `.{${unique.join(",")}}`;
+}
+function getSuggestionRoot(relativePath) {
+	if (relativePath.startsWith("src/")) return "src/";
+	const packageMatch = relativePath.match(/^packages\/([^/]+)\/src\//);
+	if (packageMatch) return `packages/${packageMatch[1]}/src/`;
+	const appMatch = relativePath.match(/^apps\/([^/]+)\/src\//);
+	if (appMatch) return `apps/${appMatch[1]}/src/`;
+	return null;
+}
+function suggestGroupedInclude(relativePaths, root) {
+	const extPattern = formatExtensionPattern(relativePaths.map((relativePath) => path.posix.extname(relativePath)));
+	if (relativePaths.map((relativePath) => path.posix.basename(relativePath, path.posix.extname(relativePath))).every((basename) => basename.toLowerCase().endsWith("machine"))) return `${root}**/*machine${extPattern}`;
+	return `${root}**/*${extPattern}`;
+}
+function suggestStatelySourceConfigs(relativePaths) {
 	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
-		});
+		suggestions.push(createSuggestedConfig(include));
 		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 groupedRoots = /* @__PURE__ */ new Map();
+	for (const relativePath of pending) {
+		const root = getSuggestionRoot(relativePath);
+		if (!root) continue;
+		const bucket = groupedRoots.get(root) ?? [];
+		bucket.push(relativePath);
+		groupedRoots.set(root, bucket);
+	}
+	for (const [root, groupedPaths] of [...groupedRoots.entries()].sort((left, right) => left[0].localeCompare(right[0]))) addSuggestion(suggestGroupedInclude(groupedPaths, root), (relativePath) => groupedPaths.includes(relativePath));
 	const byDirectory = /* @__PURE__ */ new Map();
 	for (const relativePath of pending) {
 		const directory = path.posix.dirname(relativePath);
@@ -1112,7 +1134,13 @@ async function discoverStatelySourceFiles(options = {}) {
 	} : await readStatelyProjectConfig(options);
 	const relativeFiles = await filterGitIgnoredPaths(rootDir, await walkFiles(rootDir));
 	const discovered = /* @__PURE__ */ new Map();
-	for (const source of config.sources) for (const relativePath of relativeFiles) {
+	const source = {
+		include: config.include,
+		exclude: config.exclude ?? DEFAULT_SOURCE_EXCLUDES,
+		format: "xstate",
+		xstateVersion: config.defaultXStateVersion
+	};
+	for (const relativePath of relativeFiles) {
 		if (!matchesAny(source.include, relativePath)) continue;
 		if (matchesAny(source.exclude, relativePath)) continue;
 		const filePath = path.join(rootDir, relativePath);
@@ -1414,13 +1442,28 @@ async function scanProjectSources(options) {
 		const filePath = path.join(cwd, relativePath);
 		if (looksLikeXStateMachineSource(await fsPromises.readFile(filePath, "utf8"))) machineRelativePaths.push(relativePath);
 	}
-	return suggestStatelySourceConfigs(machineRelativePaths, Math.max(5, options.defaultXStateVersion ?? 5));
+	return suggestStatelySourceConfigs(machineRelativePaths);
 }
 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 = [];
+	for (const file of files) {
+		if (looksLikeXStateMachineSource(await fsPromises.readFile(file.filePath, "utf8"))) {
+			machineFiles.push(file);
+			continue;
+		}
+		nonMachineFiles.push(file);
+	}
+	return {
+		machineFiles,
+		nonMachineFiles
+	};
+}
 function supportsMachineDiscovery(file) {
 	return file.source.format === "xstate" || file.source.format === "auto";
 }
@@ -1629,14 +1672,28 @@ var PushCommand = class PushCommand extends Command {
 		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" })
+		config: Flags.string({ description: "Path to statelyai.json" }),
+		"dry-run": Flags.boolean({
+			description: "Show which matched files contain machines and what push would do without changing remote or local state",
+			default: false
+		})
 	};
 	async run() {
 		const { args, flags } = await this.parse(PushCommand);
-		const resolvedApiKey = await resolveApiKey(flags["api-key"]);
-		if (!resolvedApiKey.apiKey) this.error(getMissingApiKeyMessage());
+		const resolvedApiKey = flags["dry-run"] ? { source: "missing" } : await resolveApiKey(flags["api-key"]);
+		if (!flags["dry-run"] && !resolvedApiKey.apiKey) this.error(getMissingApiKeyMessage());
 		this.log("Resolving configured project and source files...");
-		const { client, config, files } = await resolveConfiguredProject({
+		const { client, config, files } = flags["dry-run"] ? await (async () => {
+			const { config, rootDir } = await readStatelyProjectConfig({ configPath: flags.config });
+			return {
+				client: void 0,
+				config,
+				files: await discoverStatelySourceFiles({
+					cwd: rootDir,
+					config
+				})
+			};
+		})() : await resolveConfiguredProject({
 			apiKey: resolvedApiKey.apiKey,
 			baseUrl: flags["base-url"],
 			configPath: flags.config
@@ -1646,6 +1703,7 @@ var PushCommand = class PushCommand extends Command {
 			relativePath: path.relative(process.cwd(), path.resolve(args.file)),
 			source: {
 				include: [args.file],
+				exclude: [],
 				format: "xstate",
 				xstateVersion: config.defaultXStateVersion
 			}
@@ -1654,11 +1712,29 @@ var PushCommand = class PushCommand extends Command {
 			this.log("No matching local machine source files were discovered.");
 			return;
 		}
-		this.log(`Processing ${candidateFiles.length} ${pluralize(candidateFiles.length, "source file")}...`);
+		const { machineFiles } = await classifyPushCandidates(candidateFiles);
+		if (machineFiles.length === 0) {
+			this.log(`Matched ${candidateFiles.length} ${pluralize(candidateFiles.length, "file")}, but no local machine sources were discovered.`);
+			return;
+		}
+		this.log(`Discovered ${machineFiles.length} ${pluralize(machineFiles.length, "file with a machine")} from ${candidateFiles.length} matched ${pluralize(candidateFiles.length, "file")}.`);
+		if (flags["dry-run"]) {
+			const wouldLink = [];
+			const wouldUpdate = [];
+			for (const file of machineFiles) {
+				const pragma = getStatelyPragma(await fsPromises.readFile(file.filePath, "utf8"), file.filePath);
+				if (pragma?.id) wouldUpdate.push(`${file.relativePath}: ${pragma.id}`);
+				else wouldLink.push(file.relativePath);
+			}
+			if (wouldLink.length > 0) this.log(`Would link:\n${wouldLink.join("\n")}`);
+			if (wouldUpdate.length > 0) this.log(`Would update:\n${wouldUpdate.join("\n")}`);
+			return;
+		}
+		this.log(`Processing ${machineFiles.length} ${pluralize(machineFiles.length, "source file")}...`);
 		const linked = [];
 		const refreshed = [];
 		const skipped = [];
-		for (const file of candidateFiles) {
+		for (const file of machineFiles) {
 			this.log(`Pushing ${file.relativePath}...`);
 			if (!supportsMachineDiscovery(file)) {
 				skipped.push(`${file.relativePath}: unsupported format ${file.source.format}`);
@@ -1776,7 +1852,7 @@ var InitCommand = class InitCommand extends Command {
 				defaultXStateVersion: result.config.defaultXStateVersion
 			});
 			if (suggestions.length === 0) {
-				this.log(`${initMessage}\nNo machine source globs were suggested. Edit statelyai.json before running statelyai push.`);
+				this.log(`${initMessage}\nNo include globs were suggested from files with a machine. Edit statelyai.json before running statelyai push.`);
 				return;
 			}
 			this.log(initMessage);
@@ -1784,14 +1860,15 @@ var InitCommand = class InitCommand extends Command {
 			if (await promptYesNo("Save these source globs to statelyai.json?", true)) {
 				const nextConfig = {
 					...result.config,
-					sources: suggestions
+					include: suggestions.flatMap((suggestion) => suggestion.include),
+					exclude: [...new Set(suggestions.flatMap((suggestion) => suggestion.exclude ?? []))]
 				};
 				await fsPromises.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.");
+			} else this.log("Left statelyai.json unchanged. Edit it before running statelyai push.");
 			return;
 		}
-		this.log(`${initMessage}\nNo source globs configured yet. Edit statelyai.json before running statelyai push, or rerun with --scan.`);
+		this.log(`${initMessage}\nNo include globs configured yet. Edit statelyai.json before running statelyai push, or rerun with --scan.`);
 	}
 };
 var LoginCommand = class LoginCommand extends Command {
@@ -1883,4 +1960,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run$1();
 
 //#endregion
-export { inferInitProjectName as a, resolveApiKey as c, createStatelyProjectConfig as d, getEnvApiKey as i, run$1 as l, discoverLinkedPullTargets as n, initProject as o, formatPlanSummary as r, isFileGitDirty as s, COMMANDS as t, scanProjectSources as u };
+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 };

package/dist/index.d.mts

@@ -16,7 +16,8 @@ interface StatelyProjectConfig {
   projectId: string;
   studioUrl: string;
   defaultXStateVersion: number;
-  sources: StatelySourceConfig[];
+  include: string[];
+  exclude?: string[];
 }
 interface DiscoveredSourceFile {
   filePath: string;
@@ -54,6 +55,10 @@ interface LinkedPullTarget {
   file: DiscoveredSourceFile;
   machineId: string;
 }
+interface PushCandidateClassification {
+  machineFiles: DiscoveredSourceFile[];
+  nonMachineFiles: DiscoveredSourceFile[];
+}
 type ApiKeyResolution = {
   apiKey: string;
   detail: string;
@@ -72,7 +77,8 @@ declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string
 declare function isFileGitDirty(filePath: string): Promise<boolean>;
 declare function discoverLinkedPullTargets(files: DiscoveredSourceFile[]): Promise<LinkedPullTarget[]>;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
-declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<StatelySourceConfig[]>;
+declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<Array<Pick<StatelyProjectConfig, 'include' | 'exclude'>>>;
+declare function classifyPushCandidates(files: DiscoveredSourceFile[]): Promise<PushCandidateClassification>;
 declare function formatPlanSummary(plan: SyncPlan): string;
 declare abstract class BaseSyncCommand extends Command {
   static enableJsonFlag: boolean;
@@ -142,6 +148,7 @@ declare class PushCommand extends Command {
     '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>;
+    'dry-run': _oclif_core_interfaces0.BooleanFlag<boolean>;
   };
   run(): Promise<void>;
 }
@@ -220,4 +227,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: any, entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, ScanProjectSourcesOptions, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, PushCandidateClassification, ScanProjectSourcesOptions, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as inferInitProjectName, c as resolveApiKey, d as createStatelyProjectConfig, i as getEnvApiKey, l as run, n as discoverLinkedPullTargets, o as initProject, r as formatPlanSummary, s as isFileGitDirty, t as COMMANDS, u as scanProjectSources } from "./cli-B9CRx5db.mjs";
+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";
 
-export { COMMANDS, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };
+export { COMMANDS, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, run, scanProjectSources };

package/package.json

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