@typeonce/effect-machine-devtools 0.23.0

package/src/MachineSimulator.ts

@@ -0,0 +1,154 @@
+/**
+ * Side-effect-free, best-effort simulation over a machine document.
+ *
+ * @since 0.23.0
+ */
+import * as Schema from "effect/Schema"
+import * as internal from "./internal/machineSimulator.js"
+import type * as MachineDocument from "./MachineDocument.js"
+
+/**
+ * Serializable state of a simulation session.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Snapshot = Schema.Struct({
+  step: Schema.Natural,
+  activePaths: Schema.Array(Schema.String),
+  candidateEvents: Schema.Array(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Snapshot = Schema.Schema.Type<typeof Snapshot>
+
+/**
+ * Opaque simulation state paired with its source document.
+ *
+ * @category models
+ * @since 0.23.0
+ */
+export interface Session {
+  readonly document: MachineDocument.MachineDocument
+  readonly snapshot: Snapshot
+}
+
+/**
+ * Runtime behavior deliberately skipped by a best-effort step.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Note = Schema.Literals([
+  "runtime-effects-skipped",
+  "state-updates-skipped",
+  "reentry-lifecycles-skipped",
+  "automatic-transitions-skipped"
+])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Note = Schema.Schema.Type<typeof Note>
+
+const ResultFields = {
+  event: Schema.String,
+  transitionIds: Schema.Array(Schema.String),
+  session: Snapshot
+}
+
+/**
+ * A topologically deterministic step.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Applied = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Applied"),
+  notes: Schema.Array(Note)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Applied = Schema.Schema.Type<typeof Applied>
+
+/**
+ * An event with no registration in the current active configuration.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Blocked = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Blocked"),
+  reason: Schema.Literal("event-not-enabled")
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Blocked = Schema.Schema.Type<typeof Blocked>
+
+/**
+ * A step whose topology depends on runtime behavior the document cannot safely
+ * evaluate.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Indeterminate = Schema.Struct({
+  ...ResultFields,
+  _tag: Schema.tag("Indeterminate"),
+  reason: Schema.Literals([
+    "multiple-transitions",
+    "declinable-transition",
+    "conditional-branches",
+    "history-target",
+    "choice-target",
+    "missing-target"
+  ])
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Indeterminate = Schema.Schema.Type<typeof Indeterminate>
+
+/**
+ * @category schemas
+ * @since 0.23.0
+ */
+export const StepResult = Schema.Union([Applied, Blocked, Indeterminate])
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type StepResult = Schema.Schema.Type<typeof StepResult>
+
+/**
+ * Starts from the captured snapshot when present, otherwise from the static
+ * initial topology.
+ *
+ * @category constructors
+ * @since 0.23.0
+ */
+export const start: (document: MachineDocument.MachineDocument) => Session = internal.start
+
+/**
+ * Sends an event without running user code. `Applied` means the active topology
+ * is statically known; its notes list runtime behavior that was skipped.
+ *
+ * @category combinators
+ * @since 0.23.0
+ */
+export const send: (session: Session, event: string) => StepResult = internal.send

package/src/ProjectInspector.ts

@@ -0,0 +1,140 @@
+/**
+ * Discovery and isolated evaluation of Effect Machine definitions in a project.
+ *
+ * @since 0.23.0
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type * as DevToolsProtocol from "./DevToolsProtocol.js"
+import * as internal from "./internal/projectInspector.js"
+
+/**
+ * A source module containing at least one `.handle(...)` machine definition.
+ *
+ * @category schemas
+ * @since 0.23.0
+ */
+export const Candidate = Schema.Struct({
+  file: Schema.String,
+  exportNames: Schema.Array(Schema.String)
+})
+
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export type Candidate = Schema.Schema.Type<typeof Candidate>
+
+/**
+ * Options shared by discovery and inspection.
+ *
+ * Include and exclude entries are glob patterns relative to `root`.
+ *
+ * @category models
+ * @since 0.23.0
+ */
+export interface InspectOptions {
+  readonly root: string
+  readonly include?: string | undefined
+  readonly exclude?: ReadonlyArray<string> | undefined
+  readonly revision?: number | undefined
+  /**
+   * Last-known machine candidates. A syntactically incomplete source file is
+   * evaluated with this identity so the registry can retain its document.
+   *
+   * @internal
+   */
+  readonly retainedCandidates?: ReadonlyArray<Candidate> | undefined
+}
+
+/**
+ * A typed failure while reading or parsing the project source tree.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export class DiscoveryError extends Schema.Error<DiscoveryError>(
+  "@typeonce/effect-machine-devtools/ProjectInspector/DiscoveryError"
+)({
+  _tag: Schema.tag("DiscoveryError"),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect())
+}) {}
+
+/**
+ * A typed failure in the isolated evaluator itself. Failures in individual
+ * project modules are returned as `DevToolsProtocol.Failed` values instead.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export class EvaluationError extends Schema.Error<EvaluationError>(
+  "@typeonce/effect-machine-devtools/ProjectInspector/EvaluationError"
+)({
+  _tag: Schema.tag("EvaluationError"),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect())
+}) {}
+
+/**
+ * Service for locating and evaluating machine modules.
+ *
+ * @category services
+ * @since 0.23.0
+ */
+export class ProjectInspector extends Context.Service<ProjectInspector, {
+  readonly discover: (options: InspectOptions) => Effect.Effect<ReadonlyArray<Candidate>, DiscoveryError>
+  readonly evaluate: (
+    candidates: ReadonlyArray<Candidate>,
+    options: InspectOptions
+  ) => Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>, EvaluationError>
+  readonly inspect: (
+    options: InspectOptions
+  ) => Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>, DiscoveryError | EvaluationError>
+}>()("@typeonce/effect-machine-devtools/ProjectInspector") {}
+
+/**
+ * Discovers machine candidates with the configured inspector.
+ *
+ * @category combinators
+ * @since 0.23.0
+ */
+export const discover = (options: InspectOptions): Effect.Effect<
+  ReadonlyArray<Candidate>,
+  DiscoveryError,
+  ProjectInspector
+> => Effect.flatMap(ProjectInspector, (inspector) => inspector.discover(options))
+
+/**
+ * Evaluates machine candidates with the configured inspector.
+ *
+ * @category combinators
+ * @since 0.23.0
+ */
+export const evaluate = (
+  candidates: ReadonlyArray<Candidate>,
+  options: InspectOptions
+): Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>, EvaluationError, ProjectInspector> =>
+  Effect.flatMap(ProjectInspector, (inspector) => inspector.evaluate(candidates, options))
+
+/**
+ * Discovers and evaluates every machine candidate in a project.
+ *
+ * @category combinators
+ * @since 0.23.0
+ */
+export const inspect = (options: InspectOptions): Effect.Effect<
+  ReadonlyArray<DevToolsProtocol.MachineResult>,
+  DiscoveryError | EvaluationError,
+  ProjectInspector
+> => Effect.flatMap(ProjectInspector, (inspector) => inspector.inspect(options))
+
+/**
+ * Node-backed inspector layer. Each inspection evaluates candidates inside a
+ * fresh worker so a broken project module cannot corrupt the long-lived host.
+ *
+ * @category layers
+ * @since 0.23.0
+ */
+export const layer = internal.layer({ ProjectInspector, DiscoveryError, EvaluationError })

package/src/bin.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import PackageJson from "../package.json" with { type: "json" }
+import * as DevServer from "./DevServer.js"
+import * as MachineRegistry from "./MachineRegistry.js"
+import * as ProjectInspector from "./ProjectInspector.js"
+
+const root = Flag.directory("root", { mustExist: true }).pipe(
+  Flag.withDescription("Project root to inspect"),
+  Flag.withDefault(process.cwd())
+)
+
+const include = Flag.string("include").pipe(
+  Flag.withDescription("Machine source glob relative to the project root"),
+  Flag.withDefault("**/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}")
+)
+
+const host = Flag.string("host").pipe(
+  Flag.withDescription("Host for the local visualizer"),
+  Flag.withDefault("127.0.0.1")
+)
+
+const port = Flag.integer("port").pipe(
+  Flag.withDescription("Port for the local visualizer"),
+  Flag.withDefault(5173)
+)
+
+const open = Flag.boolean("open").pipe(
+  Flag.withDescription("Open the visualizer in the default browser"),
+  Flag.withDefault(false)
+)
+
+const watchPolling = Flag.boolean("watch-polling").pipe(
+  Flag.withDescription("Use polling instead of native file-system events"),
+  Flag.withDefault(false)
+)
+
+const cli = Command.make("effect-machine", { root, include, host, port, open, watchPolling }).pipe(
+  Command.withDescription("Inspect Effect Machine definitions in a live local visualizer"),
+  Command.withHandler(({ host, include, open, port, root, watchPolling }) => {
+    const RegistryLayer = MachineRegistry.layer({ root, include }).pipe(
+      Layer.provideMerge(ProjectInspector.layer)
+    )
+    return DevServer.run({ root, host, port, open, watchPolling }).pipe(Effect.provide(RegistryLayer))
+  })
+)
+
+Command.run(cli, { version: PackageJson.version }).pipe(
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain
+)

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Local development tools for Effect Machine.
+ *
+ * @since 0.23.0
+ */
+
+/**
+ * @since 0.23.0
+ */
+export * as DevToolsProtocol from "./DevToolsProtocol.js"
+
+/**
+ * @since 0.23.0
+ */
+export * as MachineDocument from "./MachineDocument.js"
+
+/**
+ * @since 0.23.0
+ */
+export * as MachineSimulator from "./MachineSimulator.js"

package/src/internal/browser/example-machine.ts

@@ -0,0 +1,134 @@
+import { Machine } from "@typeonce/effect-machine"
+import { Schema } from "effect"
+
+// Shared by the live browser UI and its project-inspection fixture.
+
+class Application extends Schema.TaggedClass<Application>("Application")("Application", {}) {}
+class Workflow extends Schema.TaggedClass<Workflow>("Workflow")("Workflow", {}) {}
+class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+class Running extends Schema.TaggedClass<Running>("Running")("Running", {}) {}
+class Editing extends Schema.TaggedClass<Editing>("Editing")("Editing", {}) {}
+class Complete extends Schema.TaggedClass<Complete>("Complete")("Complete", {}) {}
+class Connection extends Schema.TaggedClass<Connection>("Connection")("Connection", {}) {}
+class Online extends Schema.TaggedClass<Online>("Online")("Online", {}) {}
+class Offline extends Schema.TaggedClass<Offline>("Offline")("Offline", {}) {}
+class Disabled extends Schema.TaggedClass<Disabled>("Disabled")("Disabled", {}) {}
+class Start extends Schema.TaggedClass<Start>("Start")("Start", {}) {}
+class Finish extends Schema.TaggedClass<Finish>("Finish")("Finish", {}) {}
+class Disconnect extends Schema.TaggedClass<Disconnect>("Disconnect")("Disconnect", {}) {}
+class Refresh extends Schema.TaggedClass<Refresh>("Refresh")("Refresh", {}) {}
+
+const States = Machine.states({
+  application: {
+    schema: Application,
+    type: "parallel",
+    states: {
+      workflow: {
+        schema: Workflow,
+        initial: "idle",
+        states: {
+          idle: Idle,
+          running: {
+            schema: Running,
+            initial: "editing",
+            states: {
+              editing: Editing,
+              complete: {
+                schema: Complete,
+                type: "final"
+              }
+            }
+          },
+          recent: {
+            type: "history"
+          }
+        }
+      },
+      connection: {
+        schema: Connection,
+        initial: "online",
+        states: {
+          online: Online,
+          offline: Offline
+        }
+      }
+    }
+  },
+  disabled: Disabled
+})
+
+export const snapshot = {
+  path: "application" as const,
+  value: new Application({}),
+  states: {
+    workflow: {
+      path: "application.workflow" as const,
+      value: new Workflow({}),
+      state: { path: "application.workflow.idle" as const, value: new Idle({}) }
+    },
+    connection: {
+      path: "application.connection" as const,
+      value: new Connection({}),
+      state: { path: "application.connection.online" as const, value: new Online({}) }
+    }
+  }
+}
+
+const initialWorkflow = (): Machine.Machine.CompleteSnapshotContaining<
+  typeof States.states,
+  "application.workflow"
+> => snapshot
+
+export const machine = Machine.make({
+  id: "inspection-example",
+  states: States.states,
+  events: Machine.events(Start, Finish, Disconnect, Refresh),
+  initial: (to) => to.application.initial.resolve(() => snapshot)
+}).handle({
+  application: {
+    states: {
+      workflow: {
+        history: {
+          recent: {
+            default: initialWorkflow
+          }
+        },
+        states: {
+          idle: {
+            on: {
+              Start: (to) =>
+                to.local.running()
+                  .updating(to.branch.application.workflow)
+                  .resolve(({ owner, target }) =>
+                    target.decoded(
+                      new Running({}),
+                      (running) => running.editing.decoded(new Editing({}))
+                    ).update(owner.decoded(new Workflow({})))
+                  ),
+              Refresh: (to) => to.local.update(({ owner }) => owner.decoded(new Workflow({})))
+            }
+          },
+          running: {
+            initialize: ({ builder }) => builder.decoded(new Editing({})),
+            states: {
+              editing: {
+                on: {
+                  Finish: (to) => to.local.complete().resolve(({ target }) => target.decoded(new Complete({})))
+                }
+              }
+            }
+          }
+        }
+      },
+      connection: {
+        states: {
+          online: {
+            on: {
+              Disconnect: (to) => to.local.offline().resolve(({ target }) => target.decoded(new Offline({})))
+            }
+          }
+        }
+      }
+    }
+  }
+})

package/src/internal/browser/machine-index.ts

@@ -0,0 +1,81 @@
+import type { MachineResult, RegistrySnapshot } from "../../DevToolsProtocol.js"
+import { mountVisualizer } from "./visualizer.js"
+
+let selectedKey: string | undefined
+
+const createElement = <Tag extends keyof HTMLElementTagNameMap>(
+  tag: Tag,
+  className?: string,
+  text?: string
+): HTMLElementTagNameMap[Tag] => {
+  const element = document.createElement(tag)
+  if (className !== undefined) element.className = className
+  if (text !== undefined) element.textContent = text
+  return element
+}
+
+const resultLabel = (result: MachineResult): string => {
+  if (result._tag === "Ready" || result._tag === "Partial") return result.document.machineId
+  return result.machineId ?? result.source.exportName ?? result.source.file.split(/[\\/]/).at(-1) ?? result.key
+}
+
+const resultFile = (result: MachineResult): string =>
+  result._tag === "Ready" || result._tag === "Partial"
+    ? result.document.source?.file ?? "unknown source"
+    : result.source.file
+
+const statusLabel = (result: MachineResult): string => {
+  switch (result._tag) {
+    case "Ready":
+      return "ready"
+    case "Partial":
+      return "partial"
+    case "Failed":
+      return "error"
+  }
+}
+
+export const mountMachineIndex = (root: HTMLElement, snapshot: RegistrySnapshot): void => {
+  const results = [...snapshot.results].sort((left, right) => resultLabel(left).localeCompare(resultLabel(right)))
+  if (selectedKey === undefined || !results.some((result) => result.key === selectedKey)) {
+    selectedKey = results[0]?.key
+  }
+
+  const shell = createElement("main", "devtools-shell")
+  const index = createElement("nav", "machine-index")
+  index.setAttribute("aria-label", "Machines")
+  const view = createElement("div", "machine-view")
+
+  if (results.length === 0) {
+    index.append(createElement("div", "machine-index-empty", "No machines"))
+    const empty = createElement("div", "registry-empty")
+    empty.append(
+      createElement("strong", undefined, "No .handle machines found"),
+      createElement("span", undefined, "The list updates when a matching source file changes.")
+    )
+    view.append(empty)
+  } else {
+    for (const result of results) {
+      const button = createElement("button", `machine-row${result.key === selectedKey ? " is-selected" : ""}`)
+      button.type = "button"
+      button.dataset.machineKey = result.key
+      button.setAttribute("aria-current", result.key === selectedKey ? "true" : "false")
+      const label = createElement("span", "machine-row-label", resultLabel(result))
+      const file = createElement("span", "machine-row-file", resultFile(result))
+      const status = createElement("span", `machine-row-status status-${statusLabel(result)}`)
+      status.setAttribute("aria-label", statusLabel(result))
+      button.append(status, label, file)
+      button.addEventListener("click", () => {
+        selectedKey = result.key
+        mountMachineIndex(root, snapshot)
+      })
+      index.append(button)
+    }
+
+    const selected = results.find((result) => result.key === selectedKey) ?? results[0]
+    if (selected !== undefined) mountVisualizer(view, selected)
+  }
+
+  shell.append(index, view)
+  root.replaceChildren(shell)
+}

package/src/internal/browser/main.ts

@@ -0,0 +1,42 @@
+import * as BrowserRuntime from "@effect/platform-browser/BrowserRuntime"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import "./styles.css"
+import * as DevToolsProtocol from "../../DevToolsProtocol.js"
+import { mountMachineIndex } from "./machine-index.js"
+
+const root = document.querySelector<HTMLDivElement>("#app")
+if (root === null) throw new Error("Visualizer root element was not found")
+
+const showConnectionFailure = (message: string): void => {
+  const failure = document.createElement("div")
+  failure.className = "connection-failure"
+  failure.textContent = message
+  root.replaceChildren(failure)
+}
+
+const connect = Effect.acquireRelease(
+  Effect.sync(() => new EventSource("/api/events")),
+  (events) => Effect.sync(() => events.close())
+).pipe(
+  Effect.flatMap((events) =>
+    Effect.callback<void>((_resume, signal) => {
+      events.onmessage = (event) => {
+        try {
+          const snapshot = Schema.decodeUnknownSync(DevToolsProtocol.RegistrySnapshot)(JSON.parse(event.data))
+          mountMachineIndex(root, snapshot)
+        } catch (cause) {
+          showConnectionFailure(cause instanceof Error ? cause.message : String(cause))
+        }
+      }
+      events.onerror = () => {
+        if (events.readyState === EventSource.CLOSED) {
+          showConnectionFailure("The visualizer server disconnected. Restart the command to reconnect.")
+        }
+      }
+      signal.addEventListener("abort", () => events.close(), { once: true })
+    })
+  )
+)
+
+Effect.scoped(connect).pipe(BrowserRuntime.runMain)