@lite-fsm/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,130 @@
+# @lite-fsm/cli
+
+Alpha command line tools for `lite-fsm`. The `lite-fsm` binary can create starter React projects, add generated-store machines, export a project graph JSON document, and run a local Visualizer session for a TypeScript project.
+
+The CLI uses `@lite-fsm/graph` for static analysis. It does not run your app, call reducers, execute effects, or evaluate user code.
+
+## Install
+
+```bash
+npm install --save-dev @lite-fsm/cli
+```
+
+After installation, the `lite-fsm` command is available.
+
+## Commands
+
+| Command        | Purpose                                                                |
+| -------------- | ---------------------------------------------------------------------- |
+| `create`       | Create a starter Next.js or Vite React project wired to lite-fsm.      |
+| `add-machine`  | Add a domain machine to a generated `src/store`.                       |
+| `export-graph` | Build a project graph and write a JSON export document.                |
+| `visualize`    | Build a project graph and launch the bundled local Visualizer session. |
+
+## Create a Project
+
+Create a Next.js starter:
+
+```bash
+lite-fsm create my-app --template next
+```
+
+Create a Vite starter:
+
+```bash
+lite-fsm create my-app --template vite
+```
+
+Tailwind CSS is enabled by default. To create the same starter without Tailwind:
+
+```bash
+lite-fsm create my-app --template vite --css none
+```
+
+The generated project includes TypeScript, alias `@/*`, `@lite-fsm/core`, `@lite-fsm/react`, `@lite-fsm/middleware`, `immer`, and a minimal store under `src/store`.
+
+## Add a Machine
+
+From the root of a project created by `lite-fsm create`, add a domain machine:
+
+```bash
+lite-fsm add-machine user-session
+```
+
+This creates `src/store/machines/user-session.ts`, registers `userSession` in `src/store/index.ts`, and adds `userSession.Events` to `src/store/types.ts`.
+
+The v1 command accepts names in `kebab-case`, `snake_case`, or `camelCase` and always uses the generated store layout under `src/store`.
+
+## Export a Graph
+
+```bash
+lite-fsm export-graph --entry store/index.ts --out lite-fsm.graph.json --tsconfig tsconfig.json
+```
+
+Minimal source shape:
+
+```ts
+// store/index.ts
+import { MachineManager, createMachine } from "@lite-fsm/core";
+
+export const lamp = createMachine({
+  config: {
+    OFF: { SWITCH: "ON" },
+    ON: { SWITCH: "OFF" },
+  },
+  initialState: "OFF",
+  initialContext: {},
+});
+
+export const manager = MachineManager({ lamp });
+```
+
+The export document includes the graph, project files, source hashes, CLI diagnostics, and optional source text when `--include-source` is passed.
+
+## Run the Visualizer
+
+```bash
+lite-fsm visualize --entry store/index.ts
+```
+
+By default, `visualize` starts a local server on `127.0.0.1:3030`, opens a browser, and keeps the process running until interrupted.
+
+Useful options:
+
+```bash
+lite-fsm visualize --entry store/index.ts --tsconfig tsconfig.json --port 3031 --no-open
+```
+
+## Options
+
+`create`:
+
+- `<project-name>` - required relative target directory. Nested paths such as `apps/demo` are supported when the parent directory already exists.
+- `--template <next|vite>` - required framework template.
+- `--css <tailwind|none>` - styling preset, defaults to `tailwind`.
+- `--package-manager <pnpm|npm|yarn|bun>` - package manager for scaffold, install, and next steps, defaults to `npm`.
+- `--install` / `--no-install` - install dependencies after generation, defaults to `--install`.
+
+`add-machine`:
+
+- `<name>` - required machine name in `kebab-case`, `snake_case`, or `camelCase`. The command runs relative to the current working directory and supports the store shape generated by `lite-fsm create`.
+
+`export-graph`:
+
+- `--entry <path>` - required TypeScript entry file where the selected `MachineManager(...)` is visible.
+- `--out <path>` - required output JSON path.
+- `--tsconfig <path>` - optional explicit TypeScript config.
+- `--include-source` - embed discovered source file text in the JSON document.
+
+`visualize`:
+
+- `--entry <path>` - required TypeScript entry file.
+- `--tsconfig <path>` - optional explicit TypeScript config.
+- `--port <number>` - local Visualizer port, defaults to `3030`.
+- `--no-open` - print the session URL without opening a browser.
+
+## Documentation
+
+- [Full documentation](https://alexandergureev.github.io/lite-fsm/)
+- [CLI package guide](https://alexandergureev.github.io/lite-fsm/packages/cli)
+- [CLI API reference](https://alexandergureev.github.io/lite-fsm/api/cli)