statelyai 0.7.5 → 0.7.7

package/README.md

@@ -1,8 +1,8 @@
 # statelyai
 
-`statelyai` connects local machine source files to Stately Studio. Use it to
-open a file in the visual editor, compare local and remote machines, or sync a
-project in both directions.
+`statelyai` discovers local machine source files and can connect them to
+Stately Studio. Use it locally to inventory machines, or connect a project to
+open, compare, push, and pull machines.
 
 ## Run the CLI
 
@@ -26,8 +26,10 @@ 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                 |
-| Set up project sync          | `statelyai init [--scan]`                            | Remote project and local `statelyai.json`               |
+| 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                                                 |
 | Preview project uploads      | `statelyai push --dry-run`                           | Nothing                                                 |
 | Upload local machines        | `statelyai push [file]`                              | Remote machines and local `@statelyai` IDs              |
@@ -53,6 +55,24 @@ statelyai init --scan
 
 `--scan` suggests `include` globs and asks before saving them. Without
 `--scan`, `init` creates `statelyai.json` with an empty `include` list.
+It also lists every discovered machine with its symbol, file, line, and linked
+Stately ID when present.
+
+For local discovery without authentication or a Studio project:
+
+```bash
+statelyai init --local --scan
+statelyai status
+```
+
+Run `statelyai init` later to connect the local config to a Studio project
+without losing its discovery globs.
+
+To list machines without creating any config:
+
+```bash
+statelyai scan
+```
 
 Preview the files and remote operations:
 
@@ -114,6 +134,10 @@ environment variables.
 Stored credentials use macOS Keychain or Linux Secret Service when available,
 with a private config file as fallback. Set `STATELYAI_CREDENTIALS_BACKEND=file`
 to force file storage, or `STATELYAI_CONFIG_DIR` to choose its directory.
+Stored OAuth sessions refresh automatically before expiration. If the OAuth
+server rejects the refresh token, the CLI removes the unusable credential and
+directs you to run `npx statelyai login`. Transient refresh failures preserve
+the credential so a later command can retry.
 
 ## `statelyai.json`
 
@@ -139,16 +163,16 @@ to force file storage, or `STATELYAI_CONFIG_DIR` to choose its directory.
 | ---------------------- | --------------------------------------------------------------- |
 | `$schema`              | Published JSON Schema URL.                                      |
 | `version`              | Config format version. Currently `1.0.0`.                       |
-| `projectId`            | Remote Studio project ID.                                       |
-| `studioUrl`            | Studio API origin.                                              |
+| `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`.         |
 
-Project-wide `push` currently discovers machine-bearing JavaScript and
-TypeScript files configured as `xstate` or `auto`. The config schema accepts
-other format names, but project discovery does not push them.
+Project-wide discovery identifies every `createMachine(...)` and
+`setup(...).createMachine(...)` call in configured JavaScript and TypeScript
+files. `push` currently supports files configured as `xstate` or `auto`.
 
 Mutating project commands rewrite legacy configs with one `sources` entry to
 the current top-level shape. `status` and `push --dry-run` normalize legacy
@@ -187,6 +211,7 @@ statelyai status
 ```
 
 Statuses are `linked`, `local-only`, `remote-only`, and `missing-remote`.
+Local-only configs require no credentials and never contact Studio.
 Use `--json` for automation or `--auth` to show only credential resolution.
 `status` is read-only and never migrates `statelyai.json`.
 
@@ -194,10 +219,11 @@ Flags: `--config <path>`, `--base-url <url>`, `--json`, `--auth`.
 
 ### `init`
 
-Create or reuse a Studio project and write `statelyai.json`.
+Create a local config or reuse a Studio project and write `statelyai.json`.
 
 ```bash
 statelyai init --name "Checkout" --visibility Private --scan
+statelyai init --local --scan
 ```
 
 Flags:
@@ -205,9 +231,22 @@ Flags:
 - `--name <name>` sets the remote project name.
 - `--visibility Private|Public|Unlisted` defaults to `Private`.
 - `--scan` proposes source globs interactively.
+- `--local` skips authentication and remote project creation.
 - `--force` replaces an existing config.
 - `--base-url <url>` overrides the Studio API origin.
 
+### `scan`
+
+List every local XState machine without authentication or `statelyai.json`:
+
+```bash
+statelyai scan
+statelyai scan --json
+```
+
+The output includes the machine symbol, source file, line, and linked Stately
+ID when present.
+
 ### `open`
 
 Start a local bridge and open one source file in the browser editor:
@@ -317,6 +356,7 @@ secret environment.
 Check project discovery without network credentials or writes:
 
 ```bash
+npx statelyai scan
 npx statelyai push --dry-run
 ```
 
@@ -330,6 +370,8 @@ Set `NO_COLOR=1` or `CI=true` for plain output.
   `STATELY_ACCESS_TOKEN` or `STATELY_API_KEY`.
 - **`push` finds no files:** check `include` and `exclude`; `init` without
   `--scan` intentionally leaves `include` empty.
+- **You only need local inventory:** run `statelyai scan` or initialize with
+  `statelyai init --local --scan`; neither requires authentication.
 - **`push` matches files but finds no machines:** project discovery currently
   requires XState imports plus `createMachine(...)` or
   `setup(...).createMachine(...)`.

package/dist/bin.mjs

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

package/dist/{cli-DRKY520A.mjs → cli-DicCA4VI.mjs}

@@ -11,7 +11,7 @@ import { promisify } from "node:util";
 import { Args, Command, Flags, flush, handle, run } from "@oclif/core";
 import * as http from "node:http";
 import os from "node:os";
-import { StudioApiError, buildAuthorizeUrl, createPkcePair, createStatelyClient, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, getStatelyPragma, registerOAuthClient } from "@statelyai/sdk";
+import { StudioApiError, buildAuthorizeUrl, createPkcePair, createStatelyClient, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, findStatelyPragmaAttachments, getStatelyPragma, refreshToken, registerOAuthClient } from "@statelyai/sdk";
 import { planSync, pullSync, pushLocalMachineLinks } from "@statelyai/sdk/sync";
 
 //#region src/cliHost.ts
@@ -168,7 +168,13 @@ var RemoteEditorSession = class {
 				activePanels: []
 			});
 		} catch (error) {
-			this.showError(formatError(error, "Failed to initialize the visual editor."));
+			const message = formatError(error, "Failed to initialize the visual editor.");
+			this.postMessage({
+				type: "@statelyai.error",
+				code: "initialization_failed",
+				message
+			});
+			this.showError(message);
 			return;
 		}
 		for (const pending of this.pendingMessages) this.sendMessage(pending);
@@ -530,6 +536,8 @@ function watchWorkspace(rootDir, listener) {
 }
 function getCliWebviewContent(options) {
 	const baseUrl = normalizedBaseUrl(options.editorUrl);
+	const url = new URL(`${baseUrl}/embed`);
+	url.searchParams.set("auth", "message");
 	return `<!DOCTYPE html>
 <html lang="en" style="height:100%;margin:0">
 <head>
@@ -543,7 +551,7 @@ function getCliWebviewContent(options) {
 <body>
   <iframe
     id="stately-editor"
-    src="${escapeAttribute(new URL(`${baseUrl}/embed`).toString())}"
+    src="${escapeAttribute(url.toString())}"
     allow="clipboard-read; clipboard-write"
   ></iframe>
   <script>
@@ -793,7 +801,9 @@ function parseStoredCredential(raw, backend, location) {
 					type: "oauth",
 					accessToken: credential.accessToken,
 					...typeof credential.refreshToken === "string" ? { refreshToken: credential.refreshToken } : {},
-					...typeof credential.expiresAt === "number" ? { expiresAt: credential.expiresAt } : {}
+					...typeof credential.expiresAt === "number" ? { expiresAt: credential.expiresAt } : {},
+					...typeof credential.clientId === "string" ? { clientId: credential.clientId } : {},
+					...typeof credential.tokenEndpoint === "string" ? { tokenEndpoint: credential.tokenEndpoint } : {}
 				},
 				backend,
 				location
@@ -1064,13 +1074,21 @@ function createStatelyProjectConfig(options) {
 	return {
 		$schema: STATELY_CONFIG_SCHEMA_URL,
 		version: STATELY_CONFIG_VERSION,
-		projectId: options.projectId,
-		studioUrl: options.studioUrl,
+		projectId: options.projectId ?? "",
+		studioUrl: options.studioUrl ?? "https://stately.ai",
 		defaultXStateVersion,
 		include: [],
 		exclude: [...DEFAULT_SOURCE_EXCLUDES]
 	};
 }
+async function writeStatelyProjectConfig(configPath, config) {
+	const serialized = { ...config };
+	if (!config.projectId) {
+		delete serialized.projectId;
+		delete serialized.studioUrl;
+	}
+	await fsPromises.writeFile(configPath, `${JSON.stringify(serialized, null, 2)}\n`, "utf8");
+}
 function normalizeProjectConfig(config) {
 	const firstSource = config.sources?.[0];
 	return {
@@ -1103,7 +1121,7 @@ async function readStatelyProjectConfig(options = {}) {
 	const config = normalizeProjectConfig(parsed);
 	const rewriteStatus = getConfigRewriteStatus(parsed);
 	if (options.rewriteIfNeeded && rewriteStatus.reason === "legacy-sources") {
-		await fsPromises.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+		await writeStatelyProjectConfig(configPath, config);
 		return {
 			config,
 			configPath,
@@ -1351,7 +1369,61 @@ function getEnvCredential() {
 		variable: "NEXT_PUBLIC_STATELY_API_KEY"
 	};
 }
-async function resolveApiKey() {
+const OAUTH_EXPIRY_SKEW_MS = 6e4;
+function decodeJwtPayload(token) {
+	const [, payload] = token.split(".");
+	if (!payload) return;
+	try {
+		const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+function getOAuthExpiresAt(credential) {
+	if (credential.expiresAt !== void 0) return credential.expiresAt;
+	const exp = decodeJwtPayload(credential.accessToken)?.exp;
+	return typeof exp === "number" ? exp * 1e3 : void 0;
+}
+function isTerminalOAuthRefreshError(error) {
+	return error instanceof Error && /Token refresh failed with HTTP (?:400|401|403)\b/.test(error.message);
+}
+async function invalidateExpiredOAuthCredential() {
+	await deleteStoredApiKey();
+	throw new Error("Your Stately session expired. Run `npx statelyai login` to continue.");
+}
+async function refreshStoredOAuthCredential(credential, options) {
+	if (!credential.refreshToken) return invalidateExpiredOAuthCredential();
+	const claims = decodeJwtPayload(credential.accessToken);
+	const clientId = credential.clientId ?? (typeof claims?.client_id === "string" ? claims.client_id : void 0) ?? getConfiguredOauthClientId();
+	if (!clientId) return invalidateExpiredOAuthCredential();
+	let tokenEndpoint = credential.tokenEndpoint;
+	try {
+		if (!tokenEndpoint) tokenEndpoint = (await discoverAuthorizationServer(typeof claims?.iss === "string" ? claims.iss : getDefaultOAuthIssuer(), { fetch: options.fetch })).token_endpoint;
+	} catch (error) {
+		throw new Error("Could not refresh your expired Stately session. Retry, or run `npx statelyai login`.", { cause: error });
+	}
+	if (!tokenEndpoint) return invalidateExpiredOAuthCredential();
+	try {
+		const refreshedCredential = createOAuthCredential(await refreshToken({
+			clientId,
+			fetch: options.fetch,
+			refreshToken: credential.refreshToken,
+			tokenEndpoint
+		}), {
+			clientId,
+			fallbackRefreshToken: credential.refreshToken,
+			now: options.now,
+			tokenEndpoint
+		});
+		await setStoredCredential(refreshedCredential);
+		return refreshedCredential;
+	} catch (error) {
+		if (isTerminalOAuthRefreshError(error)) return invalidateExpiredOAuthCredential();
+		throw new Error("Could not refresh your expired Stately session. Retry, or run `npx statelyai login`.", { cause: error });
+	}
+}
+async function resolveApiKey(options = {}) {
 	const envApiKey = getEnvApiKey();
 	if (envApiKey) return {
 		apiKey: envApiKey.apiKey,
@@ -1359,11 +1431,19 @@ async function resolveApiKey() {
 		detail: envApiKey.variable
 	};
 	const storedCredential = await getStoredCredential();
-	if (storedCredential?.credential) return {
-		apiKey: storedCredential.credential.type === "oauth" ? storedCredential.credential.accessToken : storedCredential.credential.token,
-		source: "stored",
-		detail: describeCredentialBackend(storedCredential.backend, storedCredential.location)
-	};
+	if (storedCredential?.credential) {
+		let credential = storedCredential.credential;
+		const now = options.now ?? Date.now();
+		if (credential.type === "oauth" && (getOAuthExpiresAt(credential) ?? Infinity) <= now + OAUTH_EXPIRY_SKEW_MS) credential = await refreshStoredOAuthCredential(credential, {
+			...options,
+			now
+		});
+		return {
+			apiKey: credential.type === "oauth" ? credential.accessToken : credential.token,
+			source: "stored",
+			detail: describeCredentialBackend(storedCredential.backend, storedCredential.location)
+		};
+	}
 	return { source: "missing" };
 }
 function getDefaultBaseUrl() {
@@ -1530,14 +1610,17 @@ function parseOAuthCallback(value) {
 		return { code: value };
 	}
 }
-function createOAuthCredential(tokenResponse, now = Date.now()) {
+function createOAuthCredential(tokenResponse, options = {}) {
 	if (!tokenResponse.access_token) throw new Error("Token response did not include an access_token.");
+	const now = options.now ?? Date.now();
 	const expiresAt = typeof tokenResponse.expires_at === "number" ? tokenResponse.expires_at * 1e3 : typeof tokenResponse.expires_in === "number" ? now + tokenResponse.expires_in * 1e3 : void 0;
 	return {
 		type: "oauth",
 		accessToken: tokenResponse.access_token,
-		...tokenResponse.refresh_token ? { refreshToken: tokenResponse.refresh_token } : {},
-		...expiresAt ? { expiresAt } : {}
+		...tokenResponse.refresh_token ?? options.fallbackRefreshToken ? { refreshToken: tokenResponse.refresh_token ?? options.fallbackRefreshToken } : {},
+		...expiresAt ? { expiresAt } : {},
+		...options.clientId ? { clientId: options.clientId } : {},
+		...options.tokenEndpoint ? { tokenEndpoint: options.tokenEndpoint } : {}
 	};
 }
 async function buildOAuthLoginStart(options) {
@@ -1597,7 +1680,10 @@ async function runOAuthBrowserLogin(options) {
 			codeVerifier,
 			redirectUri: callbackServer.redirectUri,
 			clientId: discovery.clientId
-		})));
+		}), {
+			clientId: discovery.clientId,
+			tokenEndpoint: discovery.tokenEndpoint
+		}));
 	} finally {
 		await callbackServer.close();
 	}
@@ -1808,16 +1894,38 @@ async function initProject(options) {
 		configPath: options.configPath,
 		rewriteIfNeeded: true
 	}).catch(() => void 0) : void 0;
+	if (existingConfig) {
+		if (options.local) return {
+			config: existingConfig.config,
+			configPath: existingConfig.configPath,
+			reusedExistingConfig: true
+		};
+		if (existingConfig.config.projectId) {
+			const client = options.client ?? createStatelyClient({
+				apiKey: options.apiKey,
+				baseUrl: studioUrl
+			});
+			return {
+				config: existingConfig.config,
+				configPath: existingConfig.configPath,
+				project: await client.projects.get(existingConfig.config.projectId),
+				reusedExistingConfig: true
+			};
+		}
+	}
+	if (options.local) {
+		const config = createStatelyProjectConfig({ defaultXStateVersion });
+		await writeStatelyProjectConfig(configPath, config);
+		return {
+			config,
+			configPath,
+			reusedExistingConfig: false
+		};
+	}
 	const client = options.client ?? createStatelyClient({
 		apiKey: options.apiKey,
 		baseUrl: studioUrl
 	});
-	if (existingConfig) return {
-		config: existingConfig.config,
-		configPath: existingConfig.configPath,
-		project: await client.projects.get(existingConfig.config.projectId),
-		reusedExistingConfig: true
-	};
 	const inferredRepo = options.project?.repo ?? await inferConnectedRepoFromCwd(cwd);
 	const projectInput = {
 		name: options.project?.name ?? inferInitProjectName(cwd, inferredRepo),
@@ -1827,12 +1935,16 @@ async function initProject(options) {
 		...inferredRepo ? { repo: inferredRepo } : {}
 	};
 	const project = await client.projects.ensure(projectInput);
-	const config = createStatelyProjectConfig({
+	const config = existingConfig ? {
+		...existingConfig.config,
+		projectId: project.projectId,
+		studioUrl
+	} : createStatelyProjectConfig({
 		projectId: project.projectId,
 		studioUrl,
 		defaultXStateVersion
 	});
-	await fsPromises.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+	await writeStatelyProjectConfig(configPath, config);
 	return {
 		config,
 		configPath,
@@ -1840,15 +1952,66 @@ async function initProject(options) {
 		reusedExistingConfig: false
 	};
 }
+function inferDiscoveredMachineName(options) {
+	const declaration = options.source.slice(options.attachStart, options.machineStart);
+	const variableName = [...declaration.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)].at(-1)?.[1];
+	if (variableName) return variableName;
+	if (/\bexport\s+default\b/.test(declaration)) return "default";
+	const configuredId = options.source.slice(options.machineStart, options.machineStart + 500).match(/\bid\s*:\s*['"]([^'"]+)['"]/)?.[1];
+	if (configuredId) return configuredId;
+	return `${path.basename(options.relativePath, path.extname(options.relativePath))}#${options.machineIndex + 1}`;
+}
+function discoverMachinesInSource(options) {
+	if (!looksLikeXStateMachineSource(options.source)) return [];
+	return findStatelyPragmaAttachments(options.source, options.filePath).map((attachment, machineIndex) => ({
+		filePath: options.filePath,
+		...attachment.pragma?.id ? { id: attachment.pragma.id } : {},
+		line: options.source.slice(0, attachment.machineStart).split(/\r?\n/).length,
+		machineIndex,
+		name: inferDiscoveredMachineName({
+			attachStart: attachment.attachStart,
+			machineIndex,
+			machineStart: attachment.machineStart,
+			relativePath: options.relativePath,
+			source: options.source
+		}),
+		relativePath: options.relativePath
+	}));
+}
+async function discoverMachinesInFiles(files) {
+	const machines = [];
+	for (const file of files) {
+		const source = await fsPromises.readFile(file.filePath, "utf8");
+		machines.push(...discoverMachinesInSource({
+			filePath: file.filePath,
+			relativePath: file.relativePath,
+			source
+		}));
+	}
+	return machines;
+}
+async function scanProjectMachines(options = {}) {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	return discoverMachinesInFiles((await discoverCodeSourceFiles({ cwd })).map((relativePath) => ({
+		filePath: path.join(cwd, relativePath),
+		relativePath,
+		source: {
+			include: [relativePath],
+			exclude: [],
+			format: "xstate",
+			xstateVersion: 5
+		}
+	})));
+}
+function formatDiscoveredMachines(machines) {
+	const fileCount = new Set(machines.map((machine) => machine.relativePath)).size;
+	const lines = [`Found ${machines.length} ${pluralize(machines.length, "machine")} in ${fileCount} ${pluralize(fileCount, "file")}:`];
+	for (const machine of machines) lines.push(`  ${machine.name}  ${machine.relativePath}:${machine.line}${machine.id ? `  ${machine.id}` : ""}`);
+	return lines.join("\n");
+}
 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);
-		if (looksLikeXStateMachineSource(await fsPromises.readFile(filePath, "utf8"))) machineRelativePaths.push(relativePath);
-	}
-	return suggestStatelySourceConfigs(machineRelativePaths);
+	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);
@@ -1859,7 +2022,12 @@ async function classifyPushCandidates(files) {
 	const machineFiles = [];
 	const nonMachineFiles = [];
 	for (const file of files) {
-		if (looksLikeXStateMachineSource(await fsPromises.readFile(file.filePath, "utf8"))) {
+		const contents = await fsPromises.readFile(file.filePath, "utf8");
+		if (discoverMachinesInSource({
+			filePath: file.filePath,
+			relativePath: file.relativePath,
+			source: contents
+		}).length > 0) {
 			machineFiles.push(file);
 			continue;
 		}
@@ -1879,6 +2047,7 @@ async function resolveConfiguredProject(options) {
 		configPath: options.configPath,
 		rewriteIfNeeded: options.rewriteIfNeeded ?? true
 	});
+	if (!config.projectId) throw new Error("This is a local-only project. Run `statelyai init` to connect it to Stately Studio.");
 	const studioUrl = options.baseUrl ?? config.studioUrl;
 	return {
 		client: options.client ?? createStatelyClient({
@@ -1950,34 +2119,68 @@ function formatCredentialStatus(status) {
 	return status.type === "none" ? `Auth: none (${status.detail})` : `Auth: ${status.type} from ${status.source} (${status.detail})`;
 }
 async function resolveProjectStatus(options = {}) {
-	const { client, config, configPath, files } = await resolveConfiguredProject({
-		...options,
+	const { config, configPath, rootDir } = await readStatelyProjectConfig({
+		cwd: options.cwd,
+		configPath: options.configPath,
 		rewriteIfNeeded: false
 	});
-	const project = await client.projects.get(config.projectId);
-	const { machineFiles } = await classifyPushCandidates(files.filter(supportsMachineDiscovery));
-	const linkedTargets = await discoverLinkedPullTargets(machineFiles);
-	const linkedByPath = new Map(linkedTargets.map((target) => [target.file.filePath, target]));
+	const localMachines = await discoverMachinesInFiles((await discoverStatelySourceFiles({
+		cwd: rootDir,
+		config
+	})).filter(supportsMachineDiscovery));
+	const studioUrl = options.baseUrl ?? config.studioUrl;
+	if (!config.projectId) {
+		const machines = localMachines.map((machine) => ({
+			line: machine.line,
+			machineIndex: machine.machineIndex,
+			name: machine.name,
+			path: machine.relativePath,
+			status: "local-only"
+		}));
+		return {
+			auth: {
+				detail: "not required for local projects",
+				source: "none",
+				type: "none"
+			},
+			configPath,
+			counts: {
+				linked: 0,
+				"local-only": machines.length,
+				"missing-remote": 0,
+				"remote-only": 0
+			},
+			machines,
+			mode: "local"
+		};
+	}
+	const apiKey = options.apiKey ?? (options.client ? void 0 : (await resolveApiKey()).apiKey);
+	const project = await (options.client ?? createStatelyClient({
+		apiKey,
+		baseUrl: studioUrl
+	})).projects.get(config.projectId);
 	const remoteById = new Map(project.machines.flatMap((machine) => {
 		const id = getProjectMachineId(machine);
 		return id ? [[id, machine]] : [];
 	}));
-	const linkedIds = new Set(linkedTargets.map((target) => target.machineId));
-	const studioUrl = options.baseUrl ?? config.studioUrl;
-	const machines = machineFiles.map((file) => {
-		const linked = linkedByPath.get(file.filePath);
-		if (!linked) return {
-			name: path.basename(file.relativePath),
-			path: file.relativePath,
+	const linkedIds = new Set(localMachines.flatMap((machine) => machine.id ? [machine.id] : []));
+	const machines = localMachines.map((machine) => {
+		if (!machine.id) return {
+			line: machine.line,
+			machineIndex: machine.machineIndex,
+			name: machine.name,
+			path: machine.relativePath,
 			status: "local-only"
 		};
-		const remote = remoteById.get(linked.machineId);
+		const remote = remoteById.get(machine.id);
 		return {
-			id: linked.machineId,
-			name: remote?.name || path.basename(file.relativePath),
-			path: file.relativePath,
+			id: machine.id,
+			line: machine.line,
+			machineIndex: machine.machineIndex,
+			name: remote?.name || machine.name,
+			path: machine.relativePath,
 			status: remote ? "linked" : "missing-remote",
-			url: buildMachineEditorUrl(studioUrl, config.projectId, linked.machineId)
+			url: buildMachineEditorUrl(studioUrl, config.projectId, machine.id)
 		};
 	});
 	for (const remote of project.machines) {
@@ -2001,6 +2204,7 @@ async function resolveProjectStatus(options = {}) {
 			"remote-only": machines.filter((machine) => machine.status === "remote-only").length
 		},
 		machines,
+		mode: "studio",
 		project: {
 			id: config.projectId,
 			...project.name ? { name: project.name } : {},
@@ -2275,10 +2479,10 @@ var PushCommand = class PushCommand extends Command {
 		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}: ${formatSecondaryText(pragma.id)}`);
-				else wouldLink.push(file.relativePath);
+			for (const machine of await discoverMachinesInFiles(machineFiles)) {
+				const location = `${machine.relativePath}:${machine.line}`;
+				if (machine.id) wouldUpdate.push(`${machine.name}  ${location}  ${formatSecondaryText(machine.id)}`);
+				else wouldLink.push(`${machine.name}  ${location}`);
 			}
 			if (wouldLink.length > 0) this.log(`${formatSectionLabel("Would link:")}\n${wouldLink.join("\n")}`);
 			if (wouldUpdate.length > 0) this.log(`${formatSectionLabel("Would update:")}\n${wouldUpdate.join("\n")}`);
@@ -2381,8 +2585,8 @@ var OpenCommand = class OpenCommand extends Command {
 };
 var InitCommand = class InitCommand extends Command {
 	static enableJsonFlag = false;
-	static summary = "Create a Stately project and write statelyai.json.";
-	static description = "Creates or reuses a remote Studio project for the current working directory and writes a local statelyai.json configuration file.";
+	static summary = "Create a local or Studio-connected statelyai.json.";
+	static description = "Creates a local configuration or reuses a remote Studio project for the current working directory.";
 	static flags = {
 		help: Flags.help({ char: "h" }),
 		"base-url": Flags.string({ description: "Base URL for Stately Studio or a self-hosted deployment" }),
@@ -2400,6 +2604,10 @@ var InitCommand = class InitCommand extends Command {
 			description: "Overwrite an existing statelyai.json file",
 			default: false
 		}),
+		local: Flags.boolean({
+			description: "Create a local-only config without authentication or Studio access",
+			default: false
+		}),
 		scan: Flags.boolean({
 			description: "Scan the repo for machine-bearing files and suggest source globs to save into statelyai.json",
 			default: false
@@ -2407,21 +2615,25 @@ var InitCommand = class InitCommand extends Command {
 	};
 	async run() {
 		const { flags } = await this.parse(InitCommand);
-		const resolvedApiKey = await resolveApiKey();
-		this.log("Creating or reusing remote project...");
+		const resolvedApiKey = flags.local ? { source: "missing" } : await resolveApiKey();
+		this.log(flags.local ? "Creating local project config..." : "Creating or reusing remote project...");
 		const result = await initProject({
 			apiKey: resolvedApiKey.apiKey,
 			baseUrl: flags["base-url"],
 			force: flags.force,
+			local: flags.local,
 			project: {
 				...flags.name ? { name: flags.name } : {},
 				visibility: flags.visibility
 			}
 		});
-		const projectEditorUrl = buildProjectEditorUrl(result.config.studioUrl, result.project.projectId);
-		const initMessage = result.reusedExistingConfig ? `Using existing statelyai.json at ${result.configPath} for project ${result.project.projectId}.\nEditor: ${projectEditorUrl}` : `Initialized project ${result.project.projectId} and wrote ${result.configPath}.\nEditor: ${projectEditorUrl}`;
+		const initMessage = result.project ? (() => {
+			const projectEditorUrl = buildProjectEditorUrl(result.config.studioUrl, result.project.projectId);
+			return result.reusedExistingConfig ? `Using existing statelyai.json at ${result.configPath} for project ${result.project.projectId}.\nEditor: ${projectEditorUrl}` : `Initialized project ${result.project.projectId} and wrote ${result.configPath}.\nEditor: ${projectEditorUrl}`;
+		})() : result.reusedExistingConfig ? `Using existing local statelyai.json at ${result.configPath}.` : `Initialized local project and wrote ${result.configPath}.`;
 		if (flags.scan) {
 			this.log("Scanning local source files...");
+			const machines = await scanProjectMachines({ cwd: path.dirname(result.configPath) });
 			const suggestions = await scanProjectSources({
 				cwd: path.dirname(result.configPath),
 				defaultXStateVersion: result.config.defaultXStateVersion
@@ -2431,6 +2643,7 @@ var InitCommand = class InitCommand extends Command {
 				return;
 			}
 			this.log(initMessage);
+			this.log(formatDiscoveredMachines(machines));
 			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);
@@ -2440,7 +2653,7 @@ var InitCommand = class InitCommand extends Command {
 					exclude: [...new Set(suggestions.flatMap((suggestion) => suggestion.exclude ?? []))],
 					...inferredNewMachineDir ? { newMachinesDir: inferredNewMachineDir } : {}
 				};
-				await fsPromises.writeFile(result.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+				await writeStatelyProjectConfig(result.configPath, nextConfig);
 				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;
@@ -2448,6 +2661,23 @@ var InitCommand = class InitCommand extends Command {
 		this.log(`${initMessage}\nNo include globs configured yet. Edit statelyai.json before running statelyai push, or rerun with --scan.`);
 	}
 };
+var ScanCommand = class ScanCommand extends Command {
+	static enableJsonFlag = false;
+	static summary = "List local state machines without authentication or config.";
+	static description = "Scans source files in the current repository and reports every discovered XState machine.";
+	static flags = {
+		help: Flags.help({ char: "h" }),
+		json: Flags.boolean({
+			description: "Print machine-readable JSON",
+			default: false
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(ScanCommand);
+		const machines = await scanProjectMachines();
+		this.log(flags.json ? JSON.stringify({ machines }, null, 2) : formatDiscoveredMachines(machines));
+	}
+};
 var LoginCommand = class LoginCommand extends Command {
 	static enableJsonFlag = false;
 	static summary = "Store Stately credentials for future CLI use.";
@@ -2495,16 +2725,20 @@ var LogoutCommand = class extends Command {
 function formatProjectStatus(result) {
 	const lines = [
 		formatCredentialStatus(result.auth),
-		`Project: ${result.project.name ? `${result.project.name} ` : ""}(${result.project.id})`,
-		`Studio: ${result.project.url}`,
+		`Mode: ${result.mode}`,
+		...result.project ? [`Project: ${result.project.name ? `${result.project.name} ` : ""}(${result.project.id})`, `Studio: ${result.project.url}`] : [],
 		`Config: ${result.configPath}`,
 		`Machines: ${result.machines.length} (${result.counts.linked} linked, ${result.counts["local-only"]} local-only, ${result.counts["remote-only"]} remote-only, ${result.counts["missing-remote"]} missing-remote)`
 	];
 	for (const machine of result.machines) {
-		const details = [machine.id, machine.path].filter(Boolean).join("  ");
+		const details = [machine.path ? `${machine.path}${machine.line ? `:${machine.line}` : ""}` : void 0, machine.id].filter(Boolean).join("  ");
 		lines.push(`  [${machine.status}] ${machine.name}${details ? `  ${details}` : ""}`);
 	}
 	const next = [];
+	if (result.mode === "local") {
+		lines.push("Next: statelyai init (connect to Studio)");
+		return lines.join("\n");
+	}
 	if (result.counts["local-only"] > 0 || result.counts["missing-remote"] > 0) next.push("statelyai push");
 	if (result.counts["remote-only"] > 0) next.push("statelyai pull");
 	if (next.length > 0) lines.push(`Next: ${next.join(", ")}`);
@@ -2533,9 +2767,7 @@ var StatusCommand = class StatusCommand extends Command {
 			this.log(flags.json ? JSON.stringify({ auth }, null, 2) : formatCredentialStatus(auth));
 			return;
 		}
-		const apiKey = (await resolveApiKey()).apiKey;
 		const result = await resolveProjectStatus({
-			apiKey,
 			baseUrl: flags["base-url"],
 			configPath: flags.config
 		});
@@ -2558,6 +2790,7 @@ const COMMANDS = {
 	pull: PullCommand,
 	push: PushCommand,
 	open: OpenCommand,
+	scan: ScanCommand,
 	status: StatusCommand,
 	init: InitCommand,
 	login: LoginCommand,
@@ -2586,4 +2819,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run$1();
 
 //#endregion
-export { createStatelyProjectConfig as S, resolveConfiguredPullTargets as _, discoverOAuthLogin as a, run$1 as b, formatPlanSummary as c, getEnvApiKey as d, getEnvCredential as f, resolveApiKey as g, isFileGitDirty as h, discoverLinkedPullTargets as i, formatProjectStatus as l, initProject as m, buildOAuthLoginStart as n, discoverRemoteProjectMachineTargets as o, inferInitProjectName as p, classifyPushCandidates as r, formatMissingNewMachineDirMessage as s, COMMANDS as t, formatStoredCredentialSource as u, resolveCredentialStatus as v, scanProjectSources as x, resolveProjectStatus as y };
+export { scanProjectMachines as C, run$1 as S, createStatelyProjectConfig as T, isFileGitDirty as _, discoverMachinesInSource as a, resolveCredentialStatus as b, formatDiscoveredMachines as c, formatProjectStatus as d, formatStoredCredentialSource as f, initProject as g, inferInitProjectName as h, discoverLinkedPullTargets as i, formatMissingNewMachineDirMessage as l, getEnvCredential as m, buildOAuthLoginStart as n, discoverOAuthLogin as o, getEnvApiKey as p, classifyPushCandidates as r, discoverRemoteProjectMachineTargets as s, COMMANDS as t, formatPlanSummary as u, resolveApiKey as v, scanProjectSources as w, resolveProjectStatus as x, resolveConfiguredPullTargets as y };

package/dist/index.d.mts

@@ -12,6 +12,8 @@ type StatelyCredential = {
   accessToken: string;
   refreshToken?: string;
   expiresAt?: number;
+  clientId?: string;
+  tokenEndpoint?: string;
 };
 type CredentialBackend = 'file' | 'linux-secret-tool' | 'macos-keychain';
 type StoredCredential = {
@@ -44,8 +46,8 @@ interface DiscoveredSourceFile {
   source: StatelySourceConfig;
 }
 declare function createStatelyProjectConfig(options: {
-  projectId: string;
-  studioUrl: string;
+  projectId?: string;
+  studioUrl?: string;
   defaultXStateVersion?: number;
 }): StatelyProjectConfig;
 //#endregion
@@ -58,18 +60,27 @@ interface InitProjectOptions {
   configPath?: string;
   defaultXStateVersion?: number;
   force?: boolean;
+  local?: boolean;
   project?: Partial<CreateProjectInput>;
 }
 interface InitProjectResult {
   config: StatelyProjectConfig;
   configPath: string;
-  project: ProjectData;
+  project?: ProjectData;
   reusedExistingConfig?: boolean;
 }
 interface ScanProjectSourcesOptions {
   cwd?: string;
   defaultXStateVersion?: number;
 }
+interface DiscoveredMachine {
+  filePath: string;
+  id?: string;
+  line: number;
+  machineIndex: number;
+  name: string;
+  relativePath: string;
+}
 interface LinkedPullTarget {
   file: DiscoveredSourceFile;
   machineId: string;
@@ -100,6 +111,8 @@ interface ResolvedConfiguredPullTargets {
 type ProjectMachineStatus = 'linked' | 'local-only' | 'missing-remote' | 'remote-only';
 interface ProjectStatusMachine {
   id?: string;
+  line?: number;
+  machineIndex?: number;
   name: string;
   path?: string;
   status: ProjectMachineStatus;
@@ -110,17 +123,22 @@ interface CredentialStatus {
   source: 'environment' | 'none' | 'stored';
   type: 'api_key' | 'none' | 'oauth';
 }
+interface ResolveApiKeyOptions {
+  fetch?: typeof fetch;
+  now?: number;
+}
 interface ProjectStatusResult {
   auth: CredentialStatus;
   configPath: string;
   counts: Record<ProjectMachineStatus, number>;
   machines: ProjectStatusMachine[];
-  project: {
+  mode: 'local' | 'studio';
+  project?: {
     id: string;
     name?: string;
     url: string;
   };
-  studioUrl: string;
+  studioUrl?: string;
 }
 type ApiKeyResolution = {
   apiKey: string;
@@ -139,7 +157,7 @@ declare function getEnvCredential(): {
   credential: StatelyCredential;
   variable: 'NEXT_PUBLIC_STATELY_API_KEY' | 'STATELY_API_KEY' | 'STATELY_ACCESS_TOKEN';
 } | undefined;
-declare function resolveApiKey(): Promise<ApiKeyResolution>;
+declare function resolveApiKey(options?: ResolveApiKeyOptions): Promise<ApiKeyResolution>;
 interface OAuthLoginDiscovery {
   authorizationServer: OAuthAuthorizationServerMetadata;
   authorizationEndpoint: string;
@@ -182,6 +200,15 @@ declare function discoverRemoteProjectMachineTargets(options: {
   client?: Pick<StudioClient, 'machines'>;
 }): Promise<RemoteProjectMachineTarget[]>;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
+declare function discoverMachinesInSource(options: {
+  filePath: string;
+  relativePath: string;
+  source: string;
+}): DiscoveredMachine[];
+declare function scanProjectMachines(options?: {
+  cwd?: string;
+}): Promise<DiscoveredMachine[]>;
+declare function formatDiscoveredMachines(machines: DiscoveredMachine[]): string;
 declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<Array<Pick<StatelyProjectConfig, 'include' | 'exclude'>>>;
 declare function classifyPushCandidates(files: DiscoveredSourceFile[]): Promise<PushCandidateClassification>;
 declare function resolveConfiguredPullTargets(options: {
@@ -295,10 +322,21 @@ 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>;
+    local: _oclif_core_interfaces0.BooleanFlag<boolean>;
     scan: _oclif_core_interfaces0.BooleanFlag<boolean>;
   };
   run(): Promise<void>;
 }
+declare class ScanCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static flags: {
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    json: _oclif_core_interfaces0.BooleanFlag<boolean>;
+  };
+  run(): Promise<void>;
+}
 declare class LoginCommand extends Command {
   static enableJsonFlag: boolean;
   static summary: string;
@@ -350,6 +388,7 @@ declare const COMMANDS: {
   pull: typeof PullCommand;
   push: typeof PushCommand;
   open: typeof OpenCommand;
+  scan: typeof ScanCommand;
   status: typeof StatusCommand;
   init: typeof InitCommand;
   login: typeof LoginCommand;
@@ -358,4 +397,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: any, entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, CredentialStatus, InitProjectOptions, InitProjectResult, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveProjectStatus, run, scanProjectSources };
+export { ApiKeyResolution, COMMANDS, CredentialStatus, DiscoveredMachine, InitProjectOptions, InitProjectResult, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolveApiKeyOptions, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, 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/dist/index.mjs

@@ -1,3 +1,3 @@
-import { S as createStatelyProjectConfig, _ as resolveConfiguredPullTargets, a as discoverOAuthLogin, b as run, c as formatPlanSummary, d as getEnvApiKey, f as getEnvCredential, g as resolveApiKey, h as isFileGitDirty, i as discoverLinkedPullTargets, l as formatProjectStatus, m as initProject, n as buildOAuthLoginStart, o as discoverRemoteProjectMachineTargets, p as inferInitProjectName, r as classifyPushCandidates, s as formatMissingNewMachineDirMessage, t as COMMANDS, u as formatStoredCredentialSource, v as resolveCredentialStatus, x as scanProjectSources, y as resolveProjectStatus } from "./cli-DRKY520A.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-DicCA4VI.mjs";
 
-export { COMMANDS, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveProjectStatus, run, scanProjectSources };
+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.7.5",
+  "version": "0.7.7",
   "description": "Command-line tools for Stately",
   "license": "MIT",
   "type": "module",