@typeonce/effect-machine-devtools 0.23.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@typeonce/effect-machine-devtools",
+  "version": "0.23.0",
+  "description": "Local development tools for Effect Machine",
+  "author": "Sandro Maglione",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typeonce-dev/effect-machine.git",
+    "directory": "packages/devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/typeonce-dev/effect-machine/issues"
+  },
+  "homepage": "https://github.com/typeonce-dev/effect-machine/tree/main/packages/devtools#readme",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "effect-machine": "./dist/bin.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./dist/index.js",
+    "./DevToolsProtocol": "./dist/DevToolsProtocol.js",
+    "./MachineDocument": "./dist/MachineDocument.js",
+    "./MachineSimulator": "./dist/MachineSimulator.js",
+    "./internal/*": null
+  },
+  "dependencies": {
+    "@effect/platform-browser": "4.0.0-rc.111",
+    "@effect/platform-node": "4.0.0-rc.111",
+    "chokidar": "4.0.3",
+    "typescript": "6.0.3",
+    "vite": "8.1.5",
+    "@typeonce/effect-machine": "^0.23.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.111"
+  },
+  "devDependencies": {
+    "@types/node": "25.7.0",
+    "effect": "4.0.0-rc.111",
+    "tsx": "4.21.0"
+  },
+  "files": [
+    "src/**/*",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/client/**/*",
+    "index.html",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && vite build --config vite.config.ts && tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "dev": "tsx src/bin.ts"
+  }
+}

package/src/DevServer.ts

@@ -0,0 +1,45 @@
+/**
+ * Local HTTP server for the Effect Machine visualizer.
+ *
+ * @since 0.23.0
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as internal from "./internal/devServer.js"
+import type * as MachineRegistry from "./MachineRegistry.js"
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export interface Options {
+  readonly root: string
+  readonly host: string
+  readonly port: number
+  readonly open?: boolean | undefined
+  readonly debounce?: number | undefined
+  readonly watchPolling?: boolean | undefined
+}
+
+/**
+ * Failure while starting or serving the local visualizer.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export class DevServerError extends Schema.Error<DevServerError>(
+  "@typeonce/effect-machine-devtools/DevServer/DevServerError"
+)({
+  _tag: Schema.tag("DevServerError"),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect())
+}) {}
+
+/**
+ * Starts the local visualizer and runs until interrupted.
+ *
+ * @category constructors
+ * @since 0.23.0
+ */
+export const run = (options: Options): Effect.Effect<never, DevServerError, MachineRegistry.MachineRegistry> =>
+  internal.run(DevServerError, options)

package/src/DevToolsProtocol.ts

@@ -0,0 +1,146 @@
+/**
+ * Versioned messages exchanged by Effect Machine devtools processes.
+ *
+ * @since 0.23.0
+ */
+import * as Schema from "effect/Schema"
+import * as MachineDocument from "./MachineDocument.js"
+
+/**
+ * Current devtools protocol version.
+ *
+ * @category models
+ * @since 0.23.0
+ */
+export const protocolVersion = 1 as const
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Location = Schema.Struct({
+  file: Schema.String,
+  line: Schema.NullOr(Schema.Natural),
+  column: Schema.NullOr(Schema.Natural)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Location = Schema.Schema.Type<typeof Location>
+
+/**
+ * A recoverable or terminal problem associated with one machine candidate.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Diagnostic = Schema.Struct({
+  severity: Schema.Literals(["warning", "error"]),
+  code: Schema.String,
+  message: Schema.String,
+  location: Schema.NullOr(Location),
+  statePath: Schema.NullOr(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Diagnostic = Schema.Schema.Type<typeof Diagnostic>
+
+const ResultFields = {
+  protocolVersion: Schema.Literal(protocolVersion),
+  key: Schema.String
+}
+
+/**
+ * A complete machine inspection result.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Ready = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Ready"),
+  document: MachineDocument.MachineDocument,
+  diagnostics: Schema.Array(Diagnostic)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Ready = Schema.Schema.Type<typeof Ready>
+
+/**
+ * A usable document accompanied by diagnostics from an incomplete reload.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Partial = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Partial"),
+  document: MachineDocument.MachineDocument,
+  diagnostics: Schema.Array(Diagnostic)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Partial = Schema.Schema.Type<typeof Partial>
+
+/**
+ * A machine candidate that could not produce a document.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Failed = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Failed"),
+  source: MachineDocument.Source,
+  machineId: Schema.NullOr(Schema.String),
+  diagnostics: Schema.Array(Diagnostic)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Failed = Schema.Schema.Type<typeof Failed>
+
+/**
+ * Schema for every result returned by discovery and evaluation.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const MachineResult = Schema.Union([Ready, Partial, Failed])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type MachineResult = Schema.Schema.Type<typeof MachineResult>
+
+/**
+ * A complete live-registry update sent to browser clients.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const RegistrySnapshot = Schema.Struct({
+  protocolVersion: Schema.Literal(protocolVersion),
+  revision: Schema.Natural,
+  results: Schema.Array(MachineResult)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type RegistrySnapshot = Schema.Schema.Type<typeof RegistrySnapshot>

package/src/MachineDocument.ts

@@ -0,0 +1,264 @@
+/**
+ * Serializable inspection documents for Effect Machine devtools.
+ *
+ * @since 0.23.0
+ */
+import type { Machine } from "@typeonce/effect-machine"
+import * as Schema from "effect/Schema"
+import * as internal from "./internal/machineDocument.js"
+
+/**
+ * Current machine document schema version.
+ *
+ * @category models
+ * @since 0.23.0
+ */
+export const schemaVersion = 1 as const
+
+/**
+ * Source module and export that produced a machine.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Source = Schema.Struct({
+  file: Schema.String,
+  exportName: Schema.NullOr(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Source = Schema.Schema.Type<typeof Source>
+
+/**
+ * Static target selection retained from a transition definition.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Selection = Schema.Struct({
+  path: Schema.NullOr(Schema.String),
+  kind: Schema.Literals(["state", "initial", "history", "choice", "update", "none"]),
+  scope: Schema.NullOr(Schema.Literals(["local", "branch", "full", "initial"]))
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Selection = Schema.Schema.Type<typeof Selection>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Initial = Schema.Struct({
+  target: Schema.String,
+  selection: Selection
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Initial = Schema.Schema.Type<typeof Initial>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const State = Schema.Struct({
+  path: Schema.String,
+  key: Schema.String,
+  order: Schema.Natural,
+  title: Schema.NullOr(Schema.String),
+  description: Schema.NullOr(Schema.String),
+  documentation: Schema.NullOr(Schema.String),
+  type: Schema.Literals(["atomic", "compound", "parallel", "final", "history", "choice"]),
+  history: Schema.NullOr(Schema.Literals(["shallow", "deep"])),
+  parent: Schema.NullOr(Schema.String),
+  children: Schema.Array(Schema.String),
+  initial: Schema.NullOr(Schema.String),
+  transitionIds: Schema.Array(Schema.String),
+  activityIds: Schema.Array(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type State = Schema.Schema.Type<typeof State>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Trigger = Schema.Union([
+  Schema.Struct({ type: Schema.tag("event"), event: Schema.String }),
+  Schema.Struct({ type: Schema.tag("always") }),
+  Schema.Struct({ type: Schema.tag("done") }),
+  Schema.Struct({ type: Schema.tag("choice") }),
+  Schema.Struct({
+    type: Schema.tag("invoke"),
+    id: Schema.String,
+    outcome: Schema.Literals(["element", "done", "failure", "snapshot"])
+  })
+])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Trigger = Schema.Schema.Type<typeof Trigger>
+
+const BranchFields = {
+  id: Schema.String,
+  target: Schema.NullOr(Schema.String),
+  selection: Selection,
+  updates: Schema.Array(Schema.String)
+}
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Branch = Schema.Union([
+  Schema.Struct({ ...BranchFields, type: Schema.tag("direct") }),
+  Schema.Struct({
+    ...BranchFields,
+    type: Schema.tag("branch"),
+    key: Schema.String,
+    title: Schema.String
+  })
+])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Branch = Schema.Schema.Type<typeof Branch>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Transition = Schema.Struct({
+  id: Schema.String,
+  source: Schema.String,
+  trigger: Trigger,
+  reenter: Schema.Boolean,
+  acceptance: Schema.Literals(["required", "declinable"]),
+  branches: Schema.Array(Branch)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Transition = Schema.Schema.Type<typeof Transition>
+
+const ActivityFields = {
+  id: Schema.String,
+  source: Schema.String,
+  lifecycleId: Schema.String
+}
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Activity = Schema.Union([
+  Schema.Struct({ ...ActivityFields, type: Schema.tag("process") }),
+  Schema.Struct({
+    ...ActivityFields,
+    type: Schema.tag("effect"),
+    outcomes: Schema.Struct({
+      success: Schema.Literal("dynamic"),
+      failure: Schema.Literals(["dynamic", "none"])
+    })
+  }),
+  Schema.Struct({
+    ...ActivityFields,
+    type: Schema.tag("timer"),
+    duration: Schema.String
+  }),
+  Schema.Struct({ ...ActivityFields, type: Schema.tag("stream") }),
+  Schema.Struct({
+    ...ActivityFields,
+    type: Schema.tag("machine"),
+    child: Schema.Struct({
+      id: Schema.String,
+      machineId: Schema.NullOr(Schema.String)
+    })
+  })
+])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Activity = Schema.Schema.Type<typeof Activity>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Snapshot = Schema.Struct({
+  activePaths: Schema.Array(Schema.String),
+  candidateEvents: Schema.Array(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Snapshot = Schema.Schema.Type<typeof Snapshot>
+
+/**
+ * Complete, versioned, JSON-safe machine inspection document.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const MachineDocument = Schema.Struct({
+  schemaVersion: Schema.Literal(schemaVersion),
+  revision: Schema.Natural,
+  source: Schema.NullOr(Source),
+  machineId: Schema.String,
+  initial: Initial,
+  roots: Schema.Array(Schema.String),
+  states: Schema.Array(State),
+  transitions: Schema.Array(Transition),
+  activities: Schema.Array(Activity),
+  snapshot: Schema.NullOr(Snapshot)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type MachineDocument = Schema.Schema.Type<typeof MachineDocument>
+
+/**
+ * Options for capturing a machine document.
+ *
+ * @category models
+ * @since 0.23.0
+ */
+export interface MakeOptions<M extends Machine.Machine.Any> {
+  readonly revision?: number | undefined
+  readonly source?: Source | undefined
+  readonly snapshot?: Machine.Machine.Snapshot<Machine.Machine.States<M>> | undefined
+}
+
+/**
+ * Captures every serializable definition exposed by Effect Machine inspection.
+ * It never evaluates transition resolvers or activity sources.
+ *
+ * @category constructors
+ * @since 0.23.0
+ */
+export const make: <M extends Machine.Machine.Any>(machine: M, options?: MakeOptions<M>) => MachineDocument =
+  internal.make

package/src/MachineRegistry.ts

@@ -0,0 +1,69 @@
+/**
+ * Live registry of machine inspection results for one project.
+ *
+ * @since 0.23.0
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type * as Stream from "effect/Stream"
+import * as DevToolsProtocol from "./DevToolsProtocol.js"
+import * as internal from "./internal/machineRegistry.js"
+import type * as ProjectInspector from "./ProjectInspector.js"
+
+/**
+ * Current registry state sent to browser clients.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Snapshot = DevToolsProtocol.RegistrySnapshot
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Snapshot = Schema.Schema.Type<typeof Snapshot>
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export interface Options extends ProjectInspector.InspectOptions {
+}
+
+/**
+ * Failure while starting the initial project inspection.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export class RegistryError extends Schema.Error<RegistryError>(
+  "@typeonce/effect-machine-devtools/MachineRegistry/RegistryError"
+)({
+  _tag: Schema.tag("RegistryError"),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect())
+}) {}
+
+/**
+ * A last-known-good machine registry. Reload failures preserve the previous
+ * document as a partial result while exposing the new diagnostics.
+ *
+ * @category services
+ * @since 0.23.0
+ */
+export class MachineRegistry extends Context.Service<MachineRegistry, {
+  readonly get: Effect.Effect<Snapshot>
+  readonly changes: Stream.Stream<Snapshot>
+  readonly refresh: Effect.Effect<Snapshot, RegistryError>
+}>()("@typeonce/effect-machine-devtools/MachineRegistry") {}
+
+/**
+ * Builds a scoped registry that scans immediately and refreshes after relevant
+ * source file changes.
+ *
+ * @category layers
+ * @since 0.23.0
+ */
+export const layer = (options: Options) => internal.layer({ MachineRegistry, RegistryError }, options)