statelyai 0.12.8 → 0.14.0

package/README.md

@@ -32,6 +32,8 @@ npm install --global statelyai
 | 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                                                 |
+| Connect to a Studio project          | `statelyai link --project <id>`                      | Project association in `statelyai.json`                  |
+| Associate an existing machine       | `statelyai link <file> --machine <id>`               | Selected source machine ID comment                      |
 | 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` |
@@ -40,7 +42,7 @@ npm install --global statelyai
 
 ## Quick start
 
-<!-- project initialization and sync flow from InitCommand, PushCommand, PullCommand, and projectConfig.ts -->
+<!-- project initialization and sync flow from InitCommand, LinkCommand, PushCommand, PullCommand, and projectConfig.ts -->
 
 For hosted Stately, authenticate once:
 
@@ -48,10 +50,11 @@ For hosted Stately, authenticate once:
 statelyai login
 ```
 
-Initialize the current repository and scan for XState files:
+Initialize local discovery, then choose the Studio project:
 
 ```bash
-statelyai init --scan
+statelyai init --local --scan
+statelyai link --project <project-id-or-url>
 ```
 
 `--scan` suggests `include` globs and asks before saving them. Without
@@ -66,8 +69,8 @@ statelyai init --local --scan
 statelyai status
 ```
 
-Run `statelyai init` later to connect the local config to a Studio project
-without losing its discovery globs.
+Run `statelyai link` later to choose a Studio project without losing discovery
+globs. Plain `init` still supports the existing connected setup for compatibility.
 
 To list machines without creating any config:
 
@@ -114,6 +117,67 @@ migrated to the shared machine key on the next save.
 New states keep their generated coordinates when clear, or move beside
 existing states when they would overlap restored layout.
 
+## Local setup and Studio linking
+
+<!-- association workflow from src/link.ts and LinkCommand in src/cli.ts -->
+
+Local configuration, Studio association, and data sync are separate steps:
+
+```bash
+statelyai init --local --scan
+statelyai login
+statelyai link --project <project-id-or-url>
+statelyai push --dry-run
+statelyai push
+```
+
+`link` without flags offers a project picker in an interactive terminal. In
+scripts, pass `--project` or explicitly create a project:
+
+```bash
+statelyai link --create --name "Checkout" --visibility Private
+```
+
+Link an existing remote machine to local source without uploading or downloading
+its definition:
+
+```bash
+statelyai link ./test.ts --machine <machine-id-or-url>
+```
+
+The remote machine must belong to the connected project. For a file containing
+multiple machines, select one with `--machine-index 0` (zero-based). This changes
+only the selected machine's `@statelyai id` comment. It does not compare or
+reconcile the two definitions. Review `push --dry-run` and choose `push` or `pull`
+when ready to sync; `linked` describes association, not equality.
+
+Use `--force` to replace an existing project or machine association. Changing the
+project retains existing source machine IDs. `link` preserves discovery globs and
+local writeback settings; it does not scan or include new files automatically.
+Plain `init` retains its existing Studio-connected behavior for compatibility.
+The executable remains `statelyai`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Unconfigured
+    Unconfigured --> Local: init --local
+    Unconfigured --> Connected: init (compatibility)
+    Unconfigured --> Connected: link
+    Local --> Connected: link
+    state Connected {
+        [*] --> LocalOnly
+        LocalOnly --> Linked: link file --machine (association only)
+        LocalOnly --> Linked: push (create remote + upload + ID)
+        Linked --> Linked: push (upload)
+        Linked --> Linked: pull (download)
+    }
+```
+
+Authentication is independent of this state machine. `open`, `scan`, and
+`push --dry-run` do not establish machine links. `--scan` proposes source globs;
+a new config without it has an empty `include` list. Project-wide `pull` creates
+remote-only files only when `newMachinesDir` is configured.
+
 ## Authentication
 
 <!-- authentication flags, environment resolution, and credential storage from src/cli.ts and src/credentials.ts -->
@@ -252,6 +316,20 @@ Use `--json` for automation or `--auth` to show only credential resolution.
 
 Flags: `--config <path>`, `--base-url <url>`, `--json`, `--auth`.
 
+### `link`
+
+Connect to Studio without moving machine definitions:
+
+```bash
+statelyai link --project <project-id-or-url>
+statelyai link --create --name "Checkout"
+statelyai link ./test.ts --machine <machine-id-or-url>
+```
+
+Flags: `--project <id|url>` or `--create`, `--name`, `--visibility`,
+`--machine <id|url>`, `--machine-index <zero-based-index>`, `--config`,
+`--base-url`, `--force`. See [Local setup and Studio linking](#local-setup-and-studio-linking).
+
 ### `init`
 
 Create a local config or reuse a Studio project and write `statelyai.json`.
@@ -270,6 +348,16 @@ Flags:
 - `--force` replaces an existing config.
 - `--base-url <url>` overrides the Studio API origin.
 
+### Alternate XState runtimes
+
+<!-- source profile selection from packages/editor-sync/src/internal/sourceLocations.ts -->
+
+`open` recognizes v6 transition-function syntax in alternate runtimes such as
+`@airconsole/xstate6`, including named `setup` variables. A separate `xstate` v5
+dependency does not determine the version of a machine using that runtime.
+Importing a machine for visualization does not execute its authored actions or
+async actor implementation.
+
 ### `scan`
 
 List every local XState machine without authentication or `statelyai.json`:

package/dist/bin.mjs

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