statelyai 0.7.4 → 0.7.6

package/README.md

@@ -1,48 +1,126 @@
 # statelyai
 
-CLI implementation for Stately.
+`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.
 
-This package contains the `statelyai` command implementation.
+## Run the CLI
 
-<!-- happy-path CLI usage and statelyai.json shape derived from packages/cli/src/cli.ts#COMMANDS and packages/cli/src/projectConfig.ts -->
-## Happy Path
+<!-- package name and binary from package.json -->
 
-1. Log in once:
+Run without installing:
+
+```bash
+npx statelyai --help
+```
+
+Or install it globally:
+
+```bash
+npm install --global statelyai
+```
+
+## Choose a workflow
+
+<!-- command capabilities and side effects from src/cli.ts#COMMANDS -->
+
+| Goal                         | Command                                              | Writes                                                  |
+| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
+| 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`               |
+| 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              |
+| Download project machines    | `statelyai pull`                                     | Linked local files and new files under `newMachinesDir` |
+| Compare two machines         | `statelyai diff <source> <target>`                   | Nothing                                                 |
+| Fail on differences in CI    | `statelyai diff <source> <target> --fail-on-changes` | Nothing                                                 |
+
+## Quick start
+
+<!-- project initialization and sync flow from InitCommand, PushCommand, PullCommand, and projectConfig.ts -->
+
+For hosted Stately, authenticate once:
 
 ```bash
 statelyai login
 ```
 
-Automation can set `STATELY_ACCESS_TOKEN` for OAuth or `STATELY_API_KEY` for
-API-key auth.
+Initialize the current repository and scan for XState files:
 
-For a custom OAuth protected resource, discover OAuth from that resource:
+```bash
+statelyai init --scan
+```
+
+`--scan` suggests `include` globs and asks before saving them. Without
+`--scan`, `init` creates `statelyai.json` with an empty `include` list.
+
+Preview the files and remote operations:
+
+```bash
+statelyai push --dry-run
+```
+
+Then push and pull:
 
 ```bash
-statelyai login --base-url http://localhost:3000/registry/api/mcp
+statelyai push
+statelyai pull
 ```
 
-`statelyai login --auth bearer` uses the same browser OAuth flow explicitly.
-`statelyai login --api-key` prompts securely for an API key, and
-`statelyai login --stdin` reads an API key from standard input. All commands use
-stored OAuth credentials or stored API keys. Free accounts open read-only
-root-level views.
+`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.
+
+## Authentication
 
-2. Initialize the current repo:
+<!-- authentication flags, environment resolution, and credential storage from src/cli.ts and src/credentials.ts -->
+
+Browser OAuth is the default:
 
 ```bash
-statelyai init
+statelyai login
 ```
 
-3. Optionally scan the repo and save suggested source globs:
+Use an API key instead:
 
 ```bash
-statelyai init --scan
+statelyai login --api-key
+```
+
+Create or manage keys in [Stately API key settings](https://stately.ai/registry/user/my-settings?tab=API+Key).
+
+For noninteractive input:
+
+```bash
+printf '%s\n' "$STATELY_API_KEY" | statelyai login --stdin
 ```
 
-If you have an older `statelyai.json` that still uses the legacy `sources` shape, the CLI will rewrite simple single-source configs automatically when it reads them.
+For automation, prefer an environment variable instead of storing a
+credential. Resolution order is:
+
+1. `STATELY_ACCESS_TOKEN`
+2. `STATELY_API_KEY`
+3. `NEXT_PUBLIC_STATELY_API_KEY`
+4. the credential stored by `statelyai login`
+
+The CLI loads `.env.local` from the current directory before resolving these
+variables.
+
+Use `statelyai status --auth` to report the selected source without printing
+the credential. `statelyai logout` removes stored credentials but does not modify
+environment variables.
 
-That writes a `statelyai.json` like:
+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.
+
+## `statelyai.json`
+
+<!-- config shape, defaults, and migration behavior from src/projectConfig.ts -->
+
+`push` and `pull` use `statelyai.json` from the current directory unless
+`--config` supplies another path.
 
 ```json
 {
@@ -53,34 +131,250 @@ That writes a `statelyai.json` like:
   "defaultXStateVersion": 5,
   "include": ["src/**/*.ts"],
   "exclude": ["**/*.test.*", "**/*.spec.*"],
-  "newMachinesDir": "src"
+  "newMachinesDir": "src/machines"
 }
 ```
 
-4. Push local machines:
+| Field                  | Purpose                                                         |
+| ---------------------- | --------------------------------------------------------------- |
+| `$schema`              | Published JSON Schema URL.                                      |
+| `version`              | Config format version. Currently `1.0.0`.                       |
+| `projectId`            | Remote Studio project ID.                                       |
+| `studioUrl`            | Studio API origin.                                              |
+| `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.
+
+Mutating project commands rewrite legacy configs with one `sources` entry to
+the current top-level shape. `status` and `push --dry-run` normalize legacy
+config in memory without writing it. Multiple legacy entries cannot be merged
+safely and require manual migration.
+
+## Commands
+
+<!-- command names, arguments, flags, defaults, and behavior from src/cli.ts#COMMANDS -->
+
+### `login`
+
+Store an OAuth credential or API key.
+
+```bash
+statelyai login
+statelyai login --api-key
+```
+
+Flags: `--api-key`, `--stdin`, `--base-url`.
+
+### `logout`
+
+```bash
+statelyai logout
+```
+
+`logout` deletes stored credentials. Environment variables are unchanged.
+
+### `status`
+
+Inspect the configured project and classify local and remote machines:
+
+```bash
+statelyai status
+```
+
+Statuses are `linked`, `local-only`, `remote-only`, and `missing-remote`.
+Use `--json` for automation or `--auth` to show only credential resolution.
+`status` is read-only and never migrates `statelyai.json`.
+
+Flags: `--config <path>`, `--base-url <url>`, `--json`, `--auth`.
+
+### `init`
+
+Create or reuse a Studio project and write `statelyai.json`.
+
+```bash
+statelyai init --name "Checkout" --visibility Private --scan
+```
+
+Flags:
+
+- `--name <name>` sets the remote project name.
+- `--visibility Private|Public|Unlisted` defaults to `Private`.
+- `--scan` proposes source globs interactively.
+- `--force` replaces an existing config.
+- `--base-url <url>` overrides the Studio API origin.
+
+### `open`
+
+Start a local bridge and open one source file in the browser editor:
+
+```bash
+statelyai open src/checkout.machine.ts
+```
+
+Saved file changes refresh the editor. Saving visual edits writes them back to
+the source file.
+
+Flags:
+
+- `--editor-url <url>` selects the editor origin. Default:
+  `https://editor.stately.ai`.
+- `--host <host>` sets the local bridge host. Default: `127.0.0.1`.
+- `--port <port>` selects a port. Default: a random available port.
+- `--no-open` starts the bridge without launching a browser.
+- `--debug` logs editor protocol messages.
+
+### `diff`
+
+Compare two locators after normalizing them to graph form:
+
+```bash
+statelyai diff src/checkout.machine.ts machine_123 --fail-on-changes
+```
+
+Locators may be:
+
+- a local JavaScript or TypeScript machine file
+- a local XState JSON, Stately graph JSON, or Studio digraph JSON file
+- 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`.
+
+### `push`
+
+Push every discovered machine in `statelyai.json`:
 
 ```bash
 statelyai push
 ```
 
-Preview what `push` would do without updating Studio or local files:
+Push one file while still using the project and defaults from the config:
+
+```bash
+statelyai push src/checkout.machine.ts
+```
+
+Preview discovery and link/update decisions without a credential:
 
 ```bash
 statelyai push --dry-run
 ```
 
-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.
+`--dry-run` does not create or update machines, write `@statelyai` IDs, or
+migrate legacy configuration.
+
+Flags: `--config <path>`, `--base-url <url>`, `--dry-run`.
+
+### `pull`
 
-5. Pull remote changes back into linked local files and create new local files for remote-only project machines when `newMachinesDir` is configured:
+Pull all linked files from the configured project:
 
 ```bash
 statelyai pull
 ```
 
-`pull` skips locally modified linked files unless you pass `--force`. New remote-only machines are written as `<machine-name>.machine.ts` inside `newMachinesDir`.
+Pull a linked file using its `@statelyai` ID:
 
-Run it without installing it globally:
+```bash
+statelyai pull src/checkout.machine.ts
+```
+
+Pull a machine ID or URL to an explicit target:
 
 ```bash
-npx statelyai --help
+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.
+
+Project-wide pull skips linked files with uncommitted Git changes. Pass
+`--force` to overwrite them. Remote-only machines are skipped until
+`newMachinesDir` is set.
+
+Flags: `--config <path>`, `--base-url <url>`, `--force`.
+
+## CI examples
+
+<!-- noninteractive and exit-code behavior from credential resolution, DiffCommand, and PushCommand -->
+
+Fail when a local machine differs from Studio:
+
+```bash
+npx statelyai diff src/checkout.machine.ts machine_123 --fail-on-changes
+```
+
+Provide `STATELY_API_KEY` or `STATELY_ACCESS_TOKEN` through the CI runner's
+secret environment.
+
+Check project discovery without network credentials or writes:
+
+```bash
+npx statelyai push --dry-run
+```
+
+Set `NO_COLOR=1` or `CI=true` for plain output.
+
+## Common problems
+
+<!-- error and safeguard behavior from src/cli.ts and src/projectConfig.ts -->
+
+- **The server returns `401`:** run `statelyai login`, or set
+  `STATELY_ACCESS_TOKEN` or `STATELY_API_KEY`.
+- **`push` finds no files:** check `include` and `exclude`; `init` without
+  `--scan` intentionally leaves `include` empty.
+- **`push` matches files but finds no machines:** project discovery currently
+  requires XState imports plus `createMachine(...)` or
+  `setup(...).createMachine(...)`.
+- **Remote-only machines are skipped:** set `newMachinesDir`, then run
+  `statelyai pull` again.
+- **`pull` refuses to overwrite a file:** commit or stash its changes, or pass
+  `--force` if overwriting is intentional.
+- **A linked remote machine was deleted or is inaccessible:** interactive
+  `push` offers to relink it as a new remote machine and replaces the local ID.
+
+Run `statelyai <command> --help` for generated command syntax and flags.
+
+## Self-hosting
+
+<!-- self-host auth and URL behavior from LoginCommand, baseUrlFlags, OpenCommand, credential resolution, and projectConfig.ts -->
+
+Skip login when the server has authentication disabled. The CLI sends no
+authorization header when no credential exists; the server decides whether
+authentication is required. This also applies to `open` editor-sync requests
+and CI commands.
+
+For OAuth, point login at the deployment's protected resource:
+
+```bash
+statelyai login --base-url https://editor.example.com/api/mcp
+```
+
+Passing only an origin uses its `/api/mcp` resource. The resource must
+advertise an authorization server. If that server does not support dynamic
+client registration, set `STATELY_OAUTH_CLIENT_ID`.
+
+URL settings are intentionally scoped:
+
+| Setting            | Used by                                  | Meaning                                                    |
+| ------------------ | ---------------------------------------- | ---------------------------------------------------------- |
+| `--base-url`       | `init`, `status`, `diff`, `push`, `pull` | Studio API origin.                                         |
+| `studioUrl`        | `statelyai.json` project sync            | Default Studio API origin for that project.                |
+| `login --base-url` | `login` only                             | OAuth protected-resource URL used for discovery.           |
+| `--editor-url`     | `open` only                              | Visual editor origin. Default `https://editor.stately.ai`. |
+
+A complete setup may look like:
+
+```bash
+statelyai login --base-url https://editor.example.com/api/mcp
+statelyai init --base-url https://studio.example.com --scan
+statelyai open src/checkout.machine.ts \
+  --editor-url https://editor.example.com
 ```

package/dist/bin.mjs

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

package/dist/{cli-CrVHYzeo.mjs → cli-D0TeuFzR.mjs}

@@ -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>
@@ -832,13 +840,10 @@ async function writeFileCredentials(apiKey) {
 		location: stored.location
 	};
 }
-async function writeFileStoredCredential(credential, authMode) {
+async function writeFileStoredCredential(credential) {
 	const configDir = getConfigDir();
 	const credentialsPath = getCredentialsFilePath();
-	const payload = authMode === "none" ? {
-		version: 1,
-		authMode: "none"
-	} : {
+	const payload = {
 		version: 1,
 		credential
 	};
@@ -853,7 +858,6 @@ async function writeFileStoredCredential(credential, authMode) {
 	await promises.chmod(credentialsPath, 384);
 	return {
 		...credential ? { credential } : {},
-		...authMode ? { authMode } : {},
 		backend: "file",
 		location: credentialsPath
 	};
@@ -893,12 +897,9 @@ async function writeMacOSKeychain(apiKey) {
 		location: stored.location
 	} : void 0;
 }
-async function writeMacOSStoredCredential(credential, authMode) {
+async function writeMacOSStoredCredential(credential) {
 	if (process.platform !== "darwin") return;
-	const payload = authMode === "none" ? {
-		version: 1,
-		authMode: "none"
-	} : {
+	const payload = {
 		version: 1,
 		credential
 	};
@@ -915,7 +916,6 @@ async function writeMacOSStoredCredential(credential, authMode) {
 		]);
 		return {
 			...credential ? { credential } : {},
-			...authMode ? { authMode } : {},
 			backend: "macos-keychain",
 			location: "macOS Keychain"
 		};
@@ -964,12 +964,9 @@ async function writeLinuxSecretTool(apiKey) {
 		location: stored.location
 	} : void 0;
 }
-async function writeLinuxStoredCredential(credential, authMode) {
+async function writeLinuxStoredCredential(credential) {
 	if (process.platform !== "linux") return;
-	const payload = authMode === "none" ? {
-		version: 1,
-		authMode: "none"
-	} : {
+	const payload = {
 		version: 1,
 		credential
 	};
@@ -985,7 +982,6 @@ async function writeLinuxStoredCredential(credential, authMode) {
 		], { input: JSON.stringify(payload) });
 		return {
 			...credential ? { credential } : {},
-			...authMode ? { authMode } : {},
 			backend: "linux-secret-tool",
 			location: "Secret Service (secret-tool)"
 		};
@@ -1020,10 +1016,6 @@ async function setStoredCredential(credential) {
 	if (shouldUseFileBackendOnly()) return writeFileStoredCredential(credential);
 	return await writeMacOSStoredCredential(credential) ?? await writeLinuxStoredCredential(credential) ?? await writeFileStoredCredential(credential);
 }
-async function setStoredNoAuth() {
-	if (shouldUseFileBackendOnly()) return writeFileStoredCredential(void 0, "none");
-	return await writeMacOSStoredCredential(void 0, "none") ?? await writeLinuxStoredCredential(void 0, "none") ?? await writeFileStoredCredential(void 0, "none");
-}
 async function deleteStoredApiKey() {
 	if (shouldUseFileBackendOnly()) {
 		const deleted = await deleteFileCredentials();
@@ -1678,9 +1670,6 @@ function formatMissingNewMachineDirMessage(options) {
 function toMachineFileStem(machineName) {
 	return (typeof machineName === "string" ? machineName : "").trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "machine";
 }
-function getMissingCredentialMessage() {
-	return `No Stately credential configured. Run \`statelyai login\`, set \`STATELY_ACCESS_TOKEN\`, or set \`STATELY_API_KEY\`.\nGet or create an API key at ${STATELY_API_KEY_SETTINGS_URL}`;
-}
 function buildProjectEditorUrl(studioUrl, projectId) {
 	return `${studioUrl.replace(/\/+$/, "")}/registry/editor/${encodeURIComponent(projectId)}`;
 }
@@ -1896,7 +1885,7 @@ async function resolveConfiguredProject(options) {
 	const { config, configPath, rootDir, rewriteStatus } = await readStatelyProjectConfig({
 		cwd: options.cwd,
 		configPath: options.configPath,
-		rewriteIfNeeded: true
+		rewriteIfNeeded: options.rewriteIfNeeded ?? true
 	});
 	const studioUrl = options.baseUrl ?? config.studioUrl;
 	return {
@@ -1942,13 +1931,102 @@ async function resolveConfiguredPullTargets(options) {
 		rewriteStatus
 	};
 }
-const sharedFlags = {
+async function resolveCredentialStatus() {
+	const envCredential = getEnvCredential();
+	if (envCredential) return {
+		detail: envCredential.variable,
+		source: "environment",
+		type: envCredential.credential.type
+	};
+	const storedCredential = await getStoredCredential();
+	if (storedCredential?.credential) return {
+		detail: describeCredentialBackend(storedCredential.backend, storedCredential.location),
+		source: "stored",
+		type: storedCredential.credential.type
+	};
+	return {
+		detail: "server decides whether authentication is required",
+		source: "none",
+		type: "none"
+	};
+}
+function getProjectMachineId(machine) {
+	const candidate = machine;
+	return candidate.machineId || candidate.id;
+}
+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,
+		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 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,
+			status: "local-only"
+		};
+		const remote = remoteById.get(linked.machineId);
+		return {
+			id: linked.machineId,
+			name: remote?.name || path.basename(file.relativePath),
+			path: file.relativePath,
+			status: remote ? "linked" : "missing-remote",
+			url: buildMachineEditorUrl(studioUrl, config.projectId, linked.machineId)
+		};
+	});
+	for (const remote of project.machines) {
+		const id = getProjectMachineId(remote);
+		if (!id || linkedIds.has(id)) continue;
+		machines.push({
+			id,
+			name: remote.name || id,
+			status: "remote-only",
+			url: buildMachineEditorUrl(studioUrl, config.projectId, id)
+		});
+	}
+	machines.sort((left, right) => left.status.localeCompare(right.status) || left.name.localeCompare(right.name));
+	return {
+		auth: await resolveCredentialStatus(),
+		configPath,
+		counts: {
+			linked: machines.filter((machine) => machine.status === "linked").length,
+			"local-only": machines.filter((machine) => machine.status === "local-only").length,
+			"missing-remote": machines.filter((machine) => machine.status === "missing-remote").length,
+			"remote-only": machines.filter((machine) => machine.status === "remote-only").length
+		},
+		machines,
+		project: {
+			id: config.projectId,
+			...project.name ? { name: project.name } : {},
+			url: buildProjectEditorUrl(studioUrl, config.projectId)
+		},
+		studioUrl
+	};
+}
+const baseUrlFlags = {
 	help: Flags.help({ char: "h" }),
+	"base-url": Flags.string({ description: "Base URL for Stately Studio or a self-hosted deployment" })
+};
+const sharedFlags = {
+	...baseUrlFlags,
 	"fail-on-changes": Flags.boolean({
 		default: false,
 		description: "Exit with a nonzero code when differences are found"
-	}),
-	"base-url": Flags.string({ description: "Base URL for Stately Studio or a self-hosted deployment" })
+	})
 };
 function formatChangeList(label, items) {
 	if (items.length === 0) return null;
@@ -1996,19 +2074,22 @@ var ParsedSyncCommand = class extends BaseSyncCommand {
 		return this.parse(command);
 	}
 };
+async function createSemanticDiff(source, target, baseUrl) {
+	return planSync({
+		source,
+		target,
+		apiKey: (await resolveApiKey()).apiKey,
+		baseUrl: baseUrl ?? getDefaultBaseUrl()
+	});
+}
 var PlanCommand = class PlanCommand extends ParsedSyncCommand {
+	static hidden = true;
 	static summary = "Plan semantic sync changes between a source and target.";
 	static description = "Resolves the source and target, normalizes both into graph form, and prints a semantic change summary.";
 	static args = sharedArgs;
 	async run() {
 		const { args, flags } = await this.parseSync(PlanCommand);
-		const apiKey = (await resolveApiKey()).apiKey;
-		const plan = await planSync({
-			source: args.source,
-			target: args.target,
-			apiKey,
-			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
-		});
+		const plan = await createSemanticDiff(args.source, args.target, flags["base-url"]);
 		this.log(formatPlanSummary(plan));
 		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
 	}
@@ -2019,13 +2100,7 @@ var DiffCommand = class DiffCommand extends ParsedSyncCommand {
 	static args = sharedArgs;
 	async run() {
 		const { args, flags } = await this.parseSync(DiffCommand);
-		const apiKey = (await resolveApiKey()).apiKey;
-		const plan = await planSync({
-			source: args.source,
-			target: args.target,
-			apiKey,
-			baseUrl: flags["base-url"] ?? getDefaultBaseUrl()
-		});
+		const plan = await createSemanticDiff(args.source, args.target, flags["base-url"]);
 		this.log(formatPlanSummary(plan));
 		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
 	}
@@ -2034,7 +2109,7 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 	static summary = "Pull a source locator into a local target file.";
 	static description = "Resolves the source, materializes it in the target format inferred from the target file, and writes the result locally. With no arguments, pulls all linked files discovered from statelyai.json.";
 	static flags = {
-		...sharedFlags,
+		...baseUrlFlags,
 		config: Flags.string({ description: "Path to statelyai.json" }),
 		force: Flags.boolean({
 			description: "Overwrite linked files even when they have local git changes",
@@ -2055,7 +2130,6 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 		const { args, flags } = await this.parseSync(PullCommand);
 		const apiKey = (await resolveApiKey()).apiKey;
 		if (!args.source) {
-			if (!apiKey) this.error(getMissingCredentialMessage());
 			this.log(colorize("Resolving configured project and linked source files...", ANSI_CYAN));
 			const { config, linkedTargets, project, remoteOnlyTargets, skipped, rewriteStatus } = await resolveConfiguredPullTargets({
 				apiKey,
@@ -2134,7 +2208,6 @@ var PullCommand = class PullCommand extends ParsedSyncCommand {
 			target = localCandidate;
 		}
 		if (!target) this.error("Missing target path. Pass `statelyai pull <machine-id|url> <file>` or `statelyai pull <linked-file>`.");
-		if (!apiKey) this.error(getMissingCredentialMessage());
 		if (!flags.force && await fileExists(target) && await isFileGitDirty(target)) this.error(`Refusing to overwrite locally modified file ${target}. Pass --force to overwrite it.`);
 		this.log(colorize(`Pulling ${source} into ${target}...`, ANSI_CYAN));
 		const result = await pullSync({
@@ -2166,12 +2239,11 @@ var PushCommand = class PushCommand extends Command {
 	async run() {
 		const { args, flags } = await this.parse(PushCommand);
 		const resolvedApiKey = flags["dry-run"] ? { source: "missing" } : await resolveApiKey();
-		if (!flags["dry-run"] && !resolvedApiKey.apiKey) this.error(getMissingCredentialMessage());
 		this.log(colorize("Resolving configured project and source files...", ANSI_CYAN));
 		const { client, config, files, rewriteStatus } = flags["dry-run"] ? await (async () => {
 			const { config, rootDir, rewriteStatus } = await readStatelyProjectConfig({
 				configPath: flags.config,
-				rewriteIfNeeded: true
+				rewriteIfNeeded: false
 			});
 			return {
 				client: void 0,
@@ -2304,7 +2376,6 @@ var OpenCommand = class OpenCommand extends Command {
 	async run() {
 		const { args, flags } = await this.parse(OpenCommand);
 		const apiKey = (await resolveApiKey()).apiKey;
-		if (!apiKey) throw new Error("No Stately credential configured. Run `statelyai login` and retry.");
 		await openEditor({
 			fileName: path.resolve(args.file),
 			editorUrl: flags["editor-url"] ?? getDefaultEditorUrl(),
@@ -2345,7 +2416,6 @@ var InitCommand = class InitCommand extends Command {
 	async run() {
 		const { flags } = await this.parse(InitCommand);
 		const resolvedApiKey = await resolveApiKey();
-		if (!resolvedApiKey.apiKey) this.error(getMissingCredentialMessage());
 		this.log("Creating or reusing remote project...");
 		const result = await initProject({
 			apiKey: resolvedApiKey.apiKey,
@@ -2397,21 +2467,10 @@ var LoginCommand = class LoginCommand extends Command {
 		stdin: Flags.boolean({
 			description: "Read the API key from standard input",
 			default: false
-		}),
-		auth: Flags.string({
-			description: "Authentication mode for the target server",
-			options: ["none", "bearer"]
 		})
 	};
 	async run() {
 		const { flags } = await this.parse(LoginCommand);
-		if ((flags["api-key"] || flags.stdin) && flags.auth === "bearer") this.error("Pass either --auth bearer or API-key login flags, not both.");
-		if (flags.auth === "none") {
-			if (flags.stdin || flags["api-key"]) this.error("Pass either --auth none or an API key, not both.");
-			const stored = await setStoredNoAuth();
-			this.log(`Stored no-auth mode in ${describeCredentialBackend(stored.backend, stored.location)}.`);
-			return;
-		}
 		if (!flags["api-key"] && !flags.stdin) {
 			const stored = await runOAuthBrowserLogin({
 				baseUrl: flags["base-url"],
@@ -2441,29 +2500,64 @@ var LogoutCommand = class extends Command {
 		this.log(`Removed stored credential from ${result.locations.join(", ")}.`);
 	}
 };
+function formatProjectStatus(result) {
+	const lines = [
+		formatCredentialStatus(result.auth),
+		`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("  ");
+		lines.push(`  [${machine.status}] ${machine.name}${details ? `  ${details}` : ""}`);
+	}
+	const next = [];
+	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(", ")}`);
+	return lines.join("\n");
+}
+var StatusCommand = class StatusCommand extends Command {
+	static enableJsonFlag = false;
+	static summary = "Show project, machine, and authentication status.";
+	static description = "Reads statelyai.json and Studio project metadata, then classifies configured machine files as linked, local-only, remote-only, or missing remotely.";
+	static flags = {
+		...baseUrlFlags,
+		auth: Flags.boolean({
+			description: "Show only credential resolution",
+			default: false
+		}),
+		config: Flags.string({ description: "Path to statelyai.json" }),
+		json: Flags.boolean({
+			description: "Print machine-readable JSON",
+			default: false
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(StatusCommand);
+		if (flags.auth) {
+			const auth = await resolveCredentialStatus();
+			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
+		});
+		this.log(flags.json ? JSON.stringify(result, null, 2) : formatProjectStatus(result));
+	}
+};
 var WhoamiCommand = class extends Command {
+	static hidden = true;
 	static enableJsonFlag = false;
 	static summary = "Show how the CLI would resolve credentials.";
 	static description = "Reports whether the CLI would use an environment variable or stored credential.";
 	static flags = { help: Flags.help({ char: "h" }) };
 	async run() {
-		const envCredential = getEnvCredential();
-		const storedCredential = await getStoredCredential();
-		const storedApiKey = storedCredential?.credential?.type === "api_key" ? {
-			apiKey: storedCredential.credential.token,
-			backend: storedCredential.backend,
-			location: storedCredential.location
-		} : void 0;
-		if (envCredential) {
-			this.log(`Credential source: environment ${envCredential.credential.type} (${envCredential.variable}).`);
-			if (storedApiKey) this.log(`Stored credential also available in ${describeCredentialBackend(storedApiKey.backend, storedApiKey.location)}.`);
-			return;
-		}
-		if (storedCredential) {
-			this.log(formatStoredCredentialSource(storedCredential));
-			return;
-		}
-		this.log(getMissingCredentialMessage());
+		this.log(formatCredentialStatus(await resolveCredentialStatus()));
 	}
 };
 const COMMANDS = {
@@ -2472,6 +2566,7 @@ const COMMANDS = {
 	pull: PullCommand,
 	push: PushCommand,
 	open: OpenCommand,
+	status: StatusCommand,
 	init: InitCommand,
 	login: LoginCommand,
 	logout: LogoutCommand,
@@ -2499,4 +2594,4 @@ function isDirectExecution() {
 if (isDirectExecution()) run$1();
 
 //#endregion
-export { run$1 as _, discoverOAuthLogin as a, formatPlanSummary as c, getEnvCredential as d, inferInitProjectName as f, resolveConfiguredPullTargets as g, resolveApiKey as h, discoverLinkedPullTargets as i, formatStoredCredentialSource as l, isFileGitDirty as m, buildOAuthLoginStart as n, discoverRemoteProjectMachineTargets as o, initProject as p, classifyPushCandidates as r, formatMissingNewMachineDirMessage as s, COMMANDS as t, getEnvApiKey as u, scanProjectSources as v, createStatelyProjectConfig as y };
+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 };

package/dist/index.d.mts

@@ -51,7 +51,7 @@ declare function createStatelyProjectConfig(options: {
 //#endregion
 //#region src/cli.d.ts
 interface InitProjectOptions {
-  apiKey: string;
+  apiKey?: string;
   baseUrl?: string;
   cwd?: string;
   client?: StudioClient;
@@ -97,6 +97,31 @@ interface ResolvedConfiguredPullTargets {
     reason?: string;
   };
 }
+type ProjectMachineStatus = 'linked' | 'local-only' | 'missing-remote' | 'remote-only';
+interface ProjectStatusMachine {
+  id?: string;
+  name: string;
+  path?: string;
+  status: ProjectMachineStatus;
+  url?: string;
+}
+interface CredentialStatus {
+  detail: string;
+  source: 'environment' | 'none' | 'stored';
+  type: 'api_key' | 'none' | 'oauth';
+}
+interface ProjectStatusResult {
+  auth: CredentialStatus;
+  configPath: string;
+  counts: Record<ProjectMachineStatus, number>;
+  machines: ProjectStatusMachine[];
+  project: {
+    id: string;
+    name?: string;
+    url: string;
+  };
+  studioUrl: string;
+}
 type ApiKeyResolution = {
   apiKey: string;
   detail: string;
@@ -162,23 +187,31 @@ declare function classifyPushCandidates(files: DiscoveredSourceFile[]): Promise<
 declare function resolveConfiguredPullTargets(options: {
   cwd?: string;
   configPath?: string;
-  apiKey: string;
+  apiKey?: string;
   baseUrl?: string;
   client?: StudioClient;
 }): Promise<ResolvedConfiguredPullTargets>;
+declare function resolveCredentialStatus(): Promise<CredentialStatus>;
+declare function resolveProjectStatus(options?: {
+  apiKey?: string;
+  baseUrl?: string;
+  client?: StudioClient;
+  configPath?: string;
+  cwd?: string;
+}): Promise<ProjectStatusResult>;
 declare function formatPlanSummary(plan: SyncPlan): string;
 declare abstract class BaseSyncCommand extends Command {
   static enableJsonFlag: boolean;
   static flags: {
-    help: _oclif_core_interfaces0.BooleanFlag<void>;
     'fail-on-changes': _oclif_core_interfaces0.BooleanFlag<boolean>;
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
     'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
 }
 declare abstract class ParsedSyncCommand extends BaseSyncCommand {
   protected parseSync<T extends typeof BaseSyncCommand>(command: T): Promise<_oclif_core_interfaces0.ParserOutput<{
-    help: void;
     'fail-on-changes': boolean;
+    help: void;
     'base-url': string | undefined;
   }, {
     [flag: string]: any;
@@ -187,6 +220,7 @@ declare abstract class ParsedSyncCommand extends BaseSyncCommand {
   }>>;
 }
 declare class PlanCommand extends ParsedSyncCommand {
+  static hidden: boolean;
   static summary: string;
   static description: string;
   static args: {
@@ -211,7 +245,6 @@ declare class PullCommand extends ParsedSyncCommand {
     config: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
     force: _oclif_core_interfaces0.BooleanFlag<boolean>;
     help: _oclif_core_interfaces0.BooleanFlag<void>;
-    'fail-on-changes': _oclif_core_interfaces0.BooleanFlag<boolean>;
     'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   static args: {
@@ -275,7 +308,6 @@ declare class LoginCommand extends Command {
     'api-key': _oclif_core_interfaces0.BooleanFlag<boolean>;
     'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
     stdin: _oclif_core_interfaces0.BooleanFlag<boolean>;
-    auth: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }
@@ -288,7 +320,22 @@ declare class LogoutCommand extends Command {
   };
   run(): Promise<void>;
 }
+declare function formatProjectStatus(result: ProjectStatusResult): string;
+declare class StatusCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static flags: {
+    auth: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    config: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    json: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+  };
+  run(): Promise<void>;
+}
 declare class WhoamiCommand extends Command {
+  static hidden: boolean;
   static enableJsonFlag: boolean;
   static summary: string;
   static description: string;
@@ -303,6 +350,7 @@ declare const COMMANDS: {
   pull: typeof PullCommand;
   push: typeof PushCommand;
   open: typeof OpenCommand;
+  status: typeof StatusCommand;
   init: typeof InitCommand;
   login: typeof LoginCommand;
   logout: typeof LogoutCommand;
@@ -310,4 +358,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: any, entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, LinkedPullTarget, OAuthLoginDiscovery, PushCandidateClassification, RemoteProjectMachineTarget, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, run, scanProjectSources };
+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 };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { _ as run, a as discoverOAuthLogin, c as formatPlanSummary, d as getEnvCredential, f as inferInitProjectName, g as resolveConfiguredPullTargets, h as resolveApiKey, i as discoverLinkedPullTargets, l as formatStoredCredentialSource, m as isFileGitDirty, n as buildOAuthLoginStart, o as discoverRemoteProjectMachineTargets, p as initProject, r as classifyPushCandidates, s as formatMissingNewMachineDirMessage, t as COMMANDS, u as getEnvApiKey, v as scanProjectSources, y as createStatelyProjectConfig } from "./cli-CrVHYzeo.mjs";
+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-D0TeuFzR.mjs";
 
-export { COMMANDS, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, run, scanProjectSources };
+export { COMMANDS, buildOAuthLoginStart, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveProjectStatus, run, scanProjectSources };

package/package.json

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