statelyai 0.3.1 → 0.4.0

package/README.md

@@ -1,38 +1,67 @@
 # statelyai
 
-<!-- package.json#name and #description — top-level summary -->
+CLI implementation for Stately.
 
-Command-line tools for Stately.
+This package contains the `statelyai` command implementation.
 
-## Usage
+<!-- 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.json#bin and delegated SDK CLI commands from ../sdk/src/cli.ts#COMMANDS -->
+1. Get an API key from [Stately API Key settings](https://stately.ai/registry/user/my-settings?tab=API+Key).
+2. Log in once:
 
-Run the Stately CLI without installing it globally:
+```bash
+statelyai login
+```
+
+3. Initialize the current repo:
 
 ```bash
-npx statelyai open ./checkout.machine.ts
+statelyai init
 ```
 
-The `statelyai` package delegates to the CLI implementation in `@statelyai/sdk`.
+4. Optionally scan the repo and save suggested source globs:
 
-Available commands:
+```bash
+statelyai init --scan
+```
 
-| Command | Description |
-| --- | --- |
-| `statelyai init` | Create or reuse a Studio project for the current directory and write `statelyai.json` with an empty `sources` array |
-| `statelyai login` | Store an API key for future CLI use |
-| `statelyai logout` | Remove a stored API key |
-| `statelyai auth status` | Show whether the CLI would use an environment variable or stored credential |
-| `statelyai plan <source> <target>` | Print a semantic sync summary |
-| `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes |
-| `statelyai push [file]` | Discover local machine sources, create remote Studio machines for unlabeled files, update linked ones, and persist returned ids |
-| `statelyai pull <source> <target>` | Materialize a source into a local target file |
-| `statelyai pull <linked-file>` | Refresh a linked local file from the `@statelyai id=...` pragma |
-| `statelyai open <file>` | Open a local file in a browser-backed visual editor session |
+That writes a `statelyai.json` like:
 
-The CLI resolves credentials in this order: `--api-key`, then `STATELY_API_KEY`/`NEXT_PUBLIC_STATELY_API_KEY`, then the key stored by `statelyai login`.
+```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.*"]
+}
+```
 
-Pass `--api-key`, set `STATELY_API_KEY`, or run `statelyai login` when the editor server requires auth. Self-hosted editor servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`.
+5. Push local machines:
 
-Run `statelyai init --scan` to detect local machine-bearing files from their contents and save suggested `sources` globs into `statelyai.json`.
+```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
+npx statelyai --help
+```

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin.mjs

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