@statelyai/sdk 0.6.1 → 0.7.1

package/README.md

@@ -206,12 +206,15 @@ Available client methods:
 | `studio.projects.get(projectId)`                                        | Fetch a project and its machines                                         |
 | `studio.machines.create({ projectVersionId, ... })`                     | Create a machine through the published REST API                          |
 | `studio.machines.createMany({ projectVersionId, ... })`                 | Compatibility wrapper around `create()` that returns a one-item array    |
+| `studio.machines.update({ id, ... })`                                   | Update a machine through the published REST API                          |
 | `studio.machines.get(machineId, { version? })`                          | Fetch a machine, optionally pinned to a version                          |
 | `studio.code.extractMachines(code, { apiKey? })`                        | Extract machine configs from source text                                 |
 
 ## Sync Helpers
 
-`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, creates the remote machine, and writes `// @statelyai id=...` back into XState source files.
+`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, updates the linked remote machine when `// @statelyai id=...` is present, otherwise creates one, and writes the pragma back into XState source files when needed.
+
+For project-scoped discovery flows, `statelyai.json` defines which local files should be scanned. The CLI `statelyai push` command uses that config to find local XState sources, creates remote Studio machines for unlabeled ones, updates already-linked ones, and writes returned `// @statelyai id=...` pragmas back into source.
 
 ```ts
 import { pushSync } from '@statelyai/sdk/sync';
@@ -232,7 +235,7 @@ const result = await pushSync({
 });
 ```
 
-Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`.
+Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`. The strict XState JSON export schema is published at `@statelyai/sdk/xstate-json.schema.json`.
 
 ```json
 {
@@ -241,17 +244,7 @@ Projects can also check in a `statelyai.json` file to describe which local sourc
   "projectId": "project_123",
   "studioUrl": "https://stately.ai",
   "defaultXStateVersion": 5,
-  "sources": [
-    {
-      "include": ["src/**/*.ts", "src/**/*.tsx"],
-      "exclude": ["**/*.test.ts", "**/dist/**"],
-      "format": "xstate"
-    },
-    {
-      "include": ["docs/**/*.mmd"],
-      "format": "mermaid"
-    }
-  ]
+  "sources": []
 }
 ```
 
@@ -423,7 +416,7 @@ const aslYaml = await embed.export('asl-yaml');
 
 <!-- supported export formats from ExportFormatMap in src/protocol.ts -->
 
-Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
+Supported formats: `xstate`, `xstate-json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
@@ -605,11 +598,15 @@ Installing the package also exposes a `statelyai` binary:
 npx statelyai open ./checkout.machine.ts
 
 statelyai init
+statelyai init --scan
 statelyai login
 statelyai auth status
 statelyai plan ./checkout.machine.ts machine-id
 statelyai diff ./checkout.machine.ts machine-id --fail-on-changes
+statelyai push
+statelyai push ./checkout.machine.ts
 statelyai pull machine-id ./checkout.machine.ts
+statelyai pull ./checkout.machine.ts
 statelyai open ./checkout.machine.ts
 ```
 
@@ -619,13 +616,15 @@ Available commands:
 
 | Command                            | Description                                                                 |
 | ---------------------------------- | --------------------------------------------------------------------------- |
-| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` |
+| `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                 |
 
 Common flags:
@@ -636,6 +635,8 @@ Common flags:
 
 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`. `login` stores the key in the OS credential store when available, with a private file fallback.
 
+`statelyai init --scan` walks local code files, detects machine-bearing files from their contents, and suggests `sources` globs to save into `statelyai.json`. Without `--scan`, `init` leaves `sources` empty so you can opt in explicitly before running `statelyai push`.
+
 `statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. When the source file contains `// @statelyai id=...` and an API key is available, the editor session also reuses the referenced remote machine layout while continuing to treat the local source as the semantic source of truth. Pass `--api-key`, set `STATELY_API_KEY`, or run `statelyai login` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
 
 ## Transport Helpers

package/dist/assetStorage.d.mts

@@ -1,4 +1,4 @@
-import { m as UploadResult } from "./protocol-CDoCcaIP.mjs";
+import { m as UploadResult } from "./protocol-s9zwsiCW.mjs";
 
 //#region src/assetStorage.d.ts
 interface AssetUploadContext {

package/dist/cli.d.mts

@@ -1,14 +1,13 @@
 import { ConnectedRepo, CreateProjectInput, ProjectData, StudioClient } from "./studio.mjs";
-import "./graph-DpBGHZwl.mjs";
 import { SyncPlan } from "./sync.mjs";
 import { Command } from "@oclif/core";
 import * as _oclif_core_interfaces0 from "@oclif/core/interfaces";
 
-//#region src/cli.d.ts
+//#region src/projectConfig.d.ts
 interface StatelySourceConfig {
   include: string[];
   exclude?: string[];
-  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'json' | 'asl-json' | 'asl-yaml' | 'auto';
+  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'xstate-json' | 'asl-json' | 'asl-yaml' | 'auto';
   xstateVersion?: number;
 }
 interface StatelyProjectConfig {
@@ -19,6 +18,13 @@ interface StatelyProjectConfig {
   defaultXStateVersion: number;
   sources: StatelySourceConfig[];
 }
+declare function createStatelyProjectConfig(options: {
+  projectId: string;
+  studioUrl: string;
+  defaultXStateVersion?: number;
+}): StatelyProjectConfig;
+//#endregion
+//#region src/cli.d.ts
 interface InitProjectOptions {
   apiKey: string;
   baseUrl?: string;
@@ -34,11 +40,10 @@ interface InitProjectResult {
   configPath: string;
   project: ProjectData;
 }
-declare function createStatelyProjectConfig(options: {
-  projectId: string;
-  studioUrl: string;
+interface ScanProjectSourcesOptions {
+  cwd?: string;
   defaultXStateVersion?: number;
-}): StatelyProjectConfig;
+}
 type ApiKeyResolution = {
   apiKey: string;
   detail: string;
@@ -55,6 +60,7 @@ declare function getEnvApiKey(): {
 declare function resolveApiKey(explicitApiKey?: string): Promise<ApiKeyResolution>;
 declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
+declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<StatelySourceConfig[]>;
 declare function formatPlanSummary(plan: SyncPlan): string;
 declare abstract class BaseSyncCommand extends Command {
   static enableJsonFlag: boolean;
@@ -100,7 +106,22 @@ declare class PullCommand extends ParsedSyncCommand {
   static description: string;
   static args: {
     source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
-    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare class PushCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    file: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  static flags: {
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    'api-key': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    config: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }
@@ -133,6 +154,7 @@ 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>;
+    scan: _oclif_core_interfaces0.BooleanFlag<boolean>;
   };
   run(): Promise<void>;
 }
@@ -169,6 +191,7 @@ declare const COMMANDS: {
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
   pull: typeof PullCommand;
+  push: typeof PushCommand;
   open: typeof OpenCommand;
   init: typeof InitCommand;
   login: typeof LoginCommand;
@@ -177,4 +200,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: string[], entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, StatelyProjectConfig, StatelySourceConfig, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, ScanProjectSourcesOptions, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run, scanProjectSources };