ablauf 0.0.1

package/README.md

@@ -0,0 +1,251 @@
+# Ablauf
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+A Nuxt module for defining state machines with typed states, directional transitions, and pluggable handler pipelines.
+
+- [✨  Release Notes](/CHANGELOG.md)
+<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/ablauf?file=playground%2Fapp.vue) -->
+<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+
+## Features
+
+- Define workflows as JSON with states, transitions, and directions
+- Transition handler pipelines — run validation, confirmation, or side-effects before a state change
+- Generic `conditions` bag on transitions for custom domain logic (e.g. `nativeOnly`, `billed`)
+- Pluggable storage via `WorkflowProvider` — built-in file provider, or bring your own (database, API, etc.)
+- `useWorkflow` composable with `getNextStates`, `findTransition`, `transition`, and more
+- Auto-imported types, composables, and server utilities
+- Hot-reload for workflow definitions and transition handlers in dev
+
+## Quick Setup
+
+Install the module:
+
+```bash
+npx nuxt module add ablauf
+```
+
+Add it to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['ablauf'],
+
+  workflow: {
+    provider: 'file',               // 'file' (default) or 'custom'
+    workflowsDir: 'server/workflows', // where JSON definitions live
+    exposeApi: true,                 // register /api/_workflow routes
+  },
+})
+```
+
+## Defining a Workflow
+
+Create a JSON file in your `workflowsDir`:
+
+```json
+// server/workflows/default.json
+{
+  "name": "default",
+  "description": "Issue Tracker",
+  "states": [
+    { "slug": "backlog",     "name": "Backlog",     "color": "#6366F1", "category": "start" },
+    { "slug": "todo",        "name": "Todo",        "color": "#3B82F6", "category": "in-progress" },
+    { "slug": "in-progress", "name": "In Progress", "color": "#F59E0B", "category": "in-progress" },
+    { "slug": "review",      "name": "Review",      "color": "#8B5CF6", "category": "in-progress" },
+    { "slug": "done",        "name": "Done",        "color": "#10B981", "category": "end" }
+  ],
+  "transitions": [
+    { "from": "backlog", "to": "todo", "direction": "forward" },
+    { "from": "todo", "to": "in-progress", "direction": "forward",
+      "handler": [{ "name": "permission", "params": { "permission": "start-work" } }] },
+    { "from": "in-progress", "to": "review", "direction": "forward" },
+    { "from": "review", "to": "done", "direction": "forward",
+      "handler": [{ "name": "confirm", "params": { "message": "Mark as done?" } }] },
+    { "from": "review", "to": "in-progress", "direction": "backward" },
+    { "from": "todo", "to": "backlog", "direction": "backward" }
+  ]
+}
+```
+
+Each state has a `category` (`start`, `in-progress`, or `end`) that controls behavior — for example, `end` states have no outgoing transitions.
+
+## Using the Composable
+
+`useWorkflow` is auto-imported and fetches a workflow by name:
+
+```vue
+<script setup>
+const workflow = await useWorkflow('default')
+
+// Get all states
+workflow.getStates()
+
+// Get possible next states from a given state
+workflow.getNextStates('todo', 'forward')
+// => ['in-progress']
+
+// Find a specific transition rule
+workflow.findTransition('todo', 'in-progress')
+
+// Execute a transition (runs handler pipeline)
+const result = await workflow.transition('todo', 'in-progress', {
+  issue: currentIssue,
+})
+// Returns the TransitionRule on success, or false if a handler blocked it
+</script>
+```
+
+## Transition Handlers
+
+Handlers are TypeScript files in `app/transitions/` that run during a transition. They can validate, prompt the user, or enrich the transition args.
+
+```ts
+// app/transitions/confirm.ts
+export default defineTransitionHandler({
+  name: 'confirm',
+  friendlyName: 'Confirm Action',
+  description: 'Asks the user to confirm before proceeding.',
+  run: async (params, _args) => {
+    const message = (params?.message as string) ?? 'Are you sure?'
+    if (!window.confirm(message)) {
+      return false // blocks the transition
+    }
+  },
+})
+```
+
+Handlers are referenced by name in the workflow JSON:
+
+```json
+{ "from": "review", "to": "done", "direction": "forward",
+  "handler": [{ "name": "confirm", "params": { "message": "Mark as done?" } }] }
+```
+
+Multiple handlers run in sequence. A handler can:
+- Return `false` to **block** the transition
+- Return an object to **merge data** into the args for subsequent handlers
+- Return nothing to **allow** the transition to proceed
+
+Set `global: true` on a handler to run it on every transition automatically.
+
+## Custom Workflow Provider
+
+The built-in file provider reads JSON from disk. For database-backed workflows, use the `custom` provider:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  workflow: {
+    provider: 'custom',
+  },
+})
+```
+
+Then register your provider in a Nitro plugin:
+
+```ts
+// server/plugins/workflow.ts
+export default defineNitroPlugin(() => {
+  setWorkflowProvider({
+    async getWorkflow(name) {
+      return await db.workflows.findOne({ name })
+    },
+    async listWorkflows() {
+      return await db.workflows.findMany()
+    },
+    // Optional: enable write operations
+    async saveWorkflow(workflow) { /* ... */ },
+    async deleteWorkflow(name) { /* ... */ },
+  })
+})
+```
+
+`setWorkflowProvider` and `useWorkflowProvider` are auto-imported in server routes.
+
+## Typed Conditions
+
+Transitions support a generic `conditions` bag for domain-specific filtering. Define your conditions shape, then pass a `conditionFilter` that decides which transitions are available based on runtime context:
+
+```ts
+interface MyConditions {
+  role?: string
+  feature?: string
+}
+
+const workflow = await useWorkflow<MyConditions>('default', {
+  conditionFilter: (rule, context) => {
+    if (rule.conditions?.role && rule.conditions.role !== context.userRole) return false
+    if (rule.conditions?.feature && !context.enabledFeatures?.includes(rule.conditions.feature)) return false
+    return true
+  },
+})
+
+// Only transitions matching the current context are returned
+workflow.getNextStates('todo', 'forward', {
+  userRole: 'admin',
+  enabledFeatures: ['beta'],
+})
+```
+
+In the workflow JSON, attach conditions to any transition:
+
+```json
+{ "from": "review", "to": "done", "direction": "forward",
+  "conditions": { "role": "admin" } }
+```
+
+## API Routes
+
+When `exposeApi` is enabled (default), two routes are registered:
+
+| Route | Description |
+| --- | --- |
+| `GET /api/_workflow` | List all workflows |
+| `GET /api/_workflow/:name` | Get a workflow by name |
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+
+  ```bash
+  # Install dependencies
+  npm install
+
+  # Generate type stubs
+  npm run dev:prepare
+
+  # Develop with the playground
+  npm run dev
+
+  # Build the playground
+  npm run dev:build
+
+  # Run ESLint
+  npm run lint
+
+  # Run Vitest
+  npm run test
+  npm run test:watch
+
+  # Release new version
+  npm run release
+  ```
+
+</details>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/ablauf/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/ablauf
+[npm-downloads-src]: https://img.shields.io/npm/dm/ablauf.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/ablauf
+[license-src]: https://img.shields.io/npm/l/ablauf.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/ablauf
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,14 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Directory for workflow definition JSON files (relative to srcDir). Default: 'server/workflows' */
+    workflowsDir?: string;
+    /** Whether to register API routes for workflows. Default: true */
+    exposeApi?: boolean;
+    /** Provider type. 'file' uses the built-in file provider. 'custom' expects you to call setWorkflowProvider() in a Nitro plugin. Default: 'file' */
+    provider?: 'file' | 'custom';
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "ablauf",
+  "configKey": "workflow",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,202 @@
+import { defineNuxtModule, createResolver, addImports, addServerImports, addTemplate, addServerHandler, updateTemplates } from '@nuxt/kit';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { consola } from 'consola';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "ablauf",
+    configKey: "workflow"
+  },
+  defaults: {
+    workflowsDir: "server/workflows",
+    exposeApi: true,
+    provider: "file"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const workflowRuntimeSpecifier = "ablauf/runtime/workflow";
+    addImports([
+      { name: "defineTransitionHandler", from: workflowRuntimeSpecifier },
+      {
+        name: "TransitionHandlerParams",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      { name: "StateArgs", from: workflowRuntimeSpecifier, type: true },
+      {
+        name: "TransitionHandlerDefinition",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      {
+        name: "TransitionRule",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      {
+        name: "TransitionHandler",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      { name: "Workflow", from: workflowRuntimeSpecifier, type: true },
+      {
+        name: "WorkflowStateDefinition",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      {
+        name: "WorkflowProvider",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      { name: "Direction", from: workflowRuntimeSpecifier, type: true },
+      {
+        name: "TransitionConditionFilter",
+        from: workflowRuntimeSpecifier,
+        type: true
+      },
+      { name: "Directions", from: workflowRuntimeSpecifier },
+      {
+        name: "TransitionHandlerError",
+        from: workflowRuntimeSpecifier
+      }
+    ]);
+    addImports([
+      {
+        name: "useWorkflow",
+        from: resolver.resolve("./runtime/composables/useWorkflow")
+      }
+    ]);
+    const handlerSpecifier = resolver.resolve("./runtime/handler");
+    addImports([
+      { name: "getTransitionHandler", from: handlerSpecifier },
+      { name: "getGlobalTransitionHandlers", from: handlerSpecifier },
+      { name: "runTransitionHandler", from: handlerSpecifier },
+      { name: "runGlobalTransitionHandlers", from: handlerSpecifier }
+    ]);
+    const providerSpecifier = resolver.resolve("./runtime/server/provider");
+    addServerImports([
+      { name: "setWorkflowProvider", from: providerSpecifier },
+      { name: "useWorkflowProvider", from: providerSpecifier }
+    ]);
+    addServerImports([
+      {
+        name: "createFileWorkflowProvider",
+        from: resolver.resolve("./runtime/server/providers/file")
+      }
+    ]);
+    const transitionsDir = join(nuxt.options.srcDir, "transitions");
+    async function scanTransitions() {
+      try {
+        const entries = await readdir(transitionsDir, { recursive: true });
+        return entries.filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts"));
+      } catch {
+        return [];
+      }
+    }
+    function generateNuxtTransitionsCode(files) {
+      const buildDir = nuxt.options.buildDir;
+      const imports = files.map((file, i) => {
+        const absolute = join(transitionsDir, file);
+        let rel = relative(buildDir, absolute).replace(/\\/g, "/");
+        if (!rel.startsWith(".")) {
+          rel = `./${rel}`;
+        }
+        return `import transition${i} from '${rel}'`;
+      });
+      const refs = files.map((_, i) => `transition${i}`);
+      return [
+        ...imports,
+        "",
+        `const transitions = [${refs.join(", ")}]`,
+        "",
+        "export function getTransition(name) {",
+        "  return transitions.find(t => t.name === name)",
+        "}",
+        "",
+        "export function getAllTransitions() {",
+        "  return transitions",
+        "}"
+      ].join("\n");
+    }
+    function generateNitroTransitionsCode(files) {
+      const imports = files.map((file, i) => {
+        const importPath = join(transitionsDir, file);
+        return `import transition${i} from '${importPath}'`;
+      });
+      const refs = files.map((_, i) => `transition${i}`);
+      return [
+        ...imports,
+        "",
+        `const transitions = [${refs.join(", ")}]`,
+        "",
+        "export function getTransition(name) {",
+        "  return transitions.find(t => t.name === name)",
+        "}",
+        "",
+        "export function getAllTransitions() {",
+        "  return transitions",
+        "}"
+      ].join("\n");
+    }
+    const template = addTemplate({
+      filename: "transitions.mjs",
+      write: true,
+      getContents: async () => {
+        const files = await scanTransitions();
+        consola.info(`Loaded ${files.length} transitions`);
+        return generateNuxtTransitionsCode(files);
+      }
+    });
+    nuxt.options.alias["#transitions"] = template.dst;
+    addImports([
+      { name: "getTransition", from: template.dst },
+      { name: "getAllTransitions", from: template.dst }
+    ]);
+    nuxt.hook("nitro:config", async (nitroConfig) => {
+      const files = await scanTransitions();
+      nitroConfig.virtual = nitroConfig.virtual || {};
+      nitroConfig.virtual["#transitions"] = generateNitroTransitionsCode(files);
+    });
+    const workflowsDir = join(
+      nuxt.options.rootDir,
+      options.workflowsDir || "server/workflows"
+    );
+    if (options.provider === "file") {
+      nuxt.hook("nitro:config", (nitroConfig) => {
+        nitroConfig.virtual = nitroConfig.virtual || {};
+        nitroConfig.virtual["#ablauf-options"] = `export const workflowsDir = ${JSON.stringify(workflowsDir)}`;
+        nitroConfig.plugins = nitroConfig.plugins || [];
+        nitroConfig.plugins.push(
+          resolver.resolve("./runtime/server/plugins/workflow-provider")
+        );
+      });
+    }
+    if (options.exposeApi !== false) {
+      addServerHandler({
+        route: "/api/_workflow",
+        method: "get",
+        handler: resolver.resolve("./runtime/server/api/workflows/index.get")
+      });
+      addServerHandler({
+        route: "/api/_workflow/:name",
+        method: "get",
+        handler: resolver.resolve("./runtime/server/api/workflows/[name].get")
+      });
+    }
+    nuxt.hook("builder:watch", async (_event, relativePath) => {
+      if (relativePath.startsWith("transitions/") || relativePath.startsWith("transitions\\")) {
+        await updateTemplates({
+          filter: (t) => t.filename === "transitions.mjs"
+        });
+      }
+      const workflowsDirRel = options.workflowsDir || "server/workflows";
+      if (relativePath.startsWith(workflowsDirRel + "/") || relativePath.startsWith(workflowsDirRel + "\\")) {
+        consola.info("Workflow definition changed:", relativePath);
+      }
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/useWorkflow.d.ts

@@ -0,0 +1,13 @@
+import type { Direction, TransitionConditionFilter, TransitionRule, Workflow, WorkflowStateDefinition } from 'ablauf/runtime/workflow';
+export interface UseWorkflowOptions<TConditions extends Record<string, unknown> = Record<string, unknown>> {
+    conditionFilter?: TransitionConditionFilter<TConditions>;
+}
+export declare function useWorkflow<TConditions extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: UseWorkflowOptions<TConditions>): Promise<{
+    workflow: Workflow<TConditions>;
+    getStates: () => WorkflowStateDefinition[];
+    getState: (slug: string) => WorkflowStateDefinition | undefined;
+    getStateColor: (slug: string) => string;
+    getNextStates: (currentState: string, direction: Direction, context?: Record<string, unknown>) => string[];
+    findTransition: (from: string, to: string) => TransitionRule<TConditions> | undefined;
+    transition: (currentState: string, newState: string, args: Record<string, unknown>) => Promise<TransitionRule<TConditions> | false>;
+}>;

package/dist/runtime/composables/useWorkflow.js

@@ -0,0 +1,79 @@
+import {
+  runGlobalTransitionHandlers,
+  runTransitionHandler
+} from "../handler.js";
+export async function useWorkflow(name, options) {
+  const workflow = await $fetch(
+    `/api/_workflow/${name}`
+  );
+  if (!workflow) {
+    throw new Error(`Workflow "${name}" not found`);
+  }
+  function getStates() {
+    return workflow.states;
+  }
+  function getState(slug) {
+    return workflow.states.find((s) => s.slug === slug);
+  }
+  function getStateColor(slug) {
+    return getState(slug)?.color ?? "#9E9E9E";
+  }
+  function getNextStates(currentState, direction, context) {
+    const stateDef = getState(currentState);
+    if (stateDef?.category === "end") {
+      return [];
+    }
+    return workflow.transitions.filter((rule) => {
+      if (rule.from === "all") {
+        return currentState !== rule.to && rule.direction === direction;
+      }
+      return rule.from === currentState && rule.direction === direction;
+    }).filter((rule) => {
+      if (!options?.conditionFilter || !context) return true;
+      return options.conditionFilter(rule, context);
+    }).map((rule) => rule.to);
+  }
+  function findTransition(from, to) {
+    return workflow.transitions.find(
+      (rule) => (rule.from === from || rule.from === "all") && rule.to === to
+    );
+  }
+  async function transition(currentState, newState, args) {
+    if (currentState === newState) {
+      return false;
+    }
+    const rule = findTransition(currentState, newState);
+    if (!rule) {
+      throw new Error(
+        `No transition from "${currentState}" to "${newState}"`
+      );
+    }
+    const fullArgs = { ...args, transition: rule };
+    await runGlobalTransitionHandlers(fullArgs);
+    if (rule.handler) {
+      for (const h of rule.handler) {
+        const result = await runTransitionHandler({
+          name: h.name,
+          params: h.params,
+          args: fullArgs
+        });
+        if (typeof result === "boolean" && result === false) {
+          return false;
+        }
+        if (typeof result === "object" && result !== null) {
+          Object.assign(fullArgs, result);
+        }
+      }
+    }
+    return rule;
+  }
+  return {
+    workflow,
+    getStates,
+    getState,
+    getStateColor,
+    getNextStates,
+    findTransition,
+    transition
+  };
+}

package/dist/runtime/handler.d.ts

@@ -0,0 +1,9 @@
+import type { TransitionHandlerDefinition, TransitionHandlerParams, StateArgs } from 'ablauf/runtime/workflow';
+export declare function getTransitionHandler(name: string): TransitionHandlerDefinition | undefined;
+export declare function getGlobalTransitionHandlers(): TransitionHandlerDefinition[];
+export declare function runTransitionHandler(options: {
+    name: string;
+    params: TransitionHandlerParams;
+    args: StateArgs;
+}): Promise<boolean | Record<string, unknown> | undefined>;
+export declare function runGlobalTransitionHandlers(args: StateArgs): Promise<void>;

package/dist/runtime/handler.js

@@ -0,0 +1,22 @@
+import { getAllTransitions } from "#transitions";
+export function getTransitionHandler(name) {
+  const transitions = getAllTransitions();
+  return transitions.find((t) => t.name === name);
+}
+export function getGlobalTransitionHandlers() {
+  const transitions = getAllTransitions();
+  return transitions.filter((t) => t.global);
+}
+export async function runTransitionHandler(options) {
+  const handler = getTransitionHandler(options.name);
+  if (!handler) {
+    throw new Error(`Transition handler "${options.name}" not found`);
+  }
+  return handler.run(options.params, options.args);
+}
+export async function runGlobalTransitionHandlers(args) {
+  const globalHandlers = getGlobalTransitionHandlers();
+  for (const handler of globalHandlers) {
+    await runTransitionHandler({ name: handler.name, params: {}, args });
+  }
+}

package/dist/runtime/server/api/workflows/[name].get.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../workflow.js").Workflow<Record<string, unknown>>>>;
+export default _default;

package/dist/runtime/server/api/workflows/[name].get.js

@@ -0,0 +1,17 @@
+import { defineEventHandler, getRouterParam, createError } from "h3";
+import { useWorkflowProvider } from "../../provider.js";
+export default defineEventHandler(async (event) => {
+  const name = getRouterParam(event, "name");
+  if (!name) {
+    throw createError({ statusCode: 400, message: "Workflow name is required" });
+  }
+  const provider = useWorkflowProvider();
+  try {
+    return await provider.getWorkflow(name);
+  } catch {
+    throw createError({
+      statusCode: 404,
+      message: `Workflow "${name}" not found`
+    });
+  }
+});

package/dist/runtime/server/api/workflows/index.get.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../workflow.js").Workflow<Record<string, unknown>>[]>>;
+export default _default;

package/dist/runtime/server/api/workflows/index.get.js

@@ -0,0 +1,6 @@
+import { defineEventHandler } from "h3";
+import { useWorkflowProvider } from "../../provider.js";
+export default defineEventHandler(async () => {
+  const provider = useWorkflowProvider();
+  return provider.listWorkflows();
+});

package/dist/runtime/server/plugins/workflow-provider.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nitropack/types").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/workflow-provider.js

@@ -0,0 +1,7 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+import { createFileWorkflowProvider } from "../providers/file.js";
+import { setWorkflowProvider } from "../provider.js";
+import { workflowsDir } from "#ablauf-options";
+export default defineNitroPlugin(() => {
+  setWorkflowProvider(createFileWorkflowProvider(workflowsDir));
+});

package/dist/runtime/server/provider.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowProvider } from 'ablauf/runtime/workflow';
+export declare function setWorkflowProvider(provider: WorkflowProvider): void;
+export declare function useWorkflowProvider(): WorkflowProvider;

package/dist/runtime/server/provider.js

@@ -0,0 +1,12 @@
+let _provider = null;
+export function setWorkflowProvider(provider) {
+  _provider = provider;
+}
+export function useWorkflowProvider() {
+  if (!_provider) {
+    throw new Error(
+      "No workflow provider configured. Call setWorkflowProvider() in a Nitro plugin or set provider option in module config."
+    );
+  }
+  return _provider;
+}

package/dist/runtime/server/providers/file.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowProvider } from 'ablauf/runtime/workflow';
+export declare function createFileWorkflowProvider(dir: string): WorkflowProvider;

package/dist/runtime/server/providers/file.js

@@ -0,0 +1,29 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function createFileWorkflowProvider(dir) {
+  return {
+    async getWorkflow(name) {
+      const filePath = join(dir, `${name}.json`);
+      try {
+        const content = await readFile(filePath, "utf-8");
+        return JSON.parse(content);
+      } catch {
+        throw new Error(`Workflow "${name}" not found at ${filePath}`);
+      }
+    },
+    async listWorkflows() {
+      try {
+        const entries = await readdir(dir);
+        const jsonFiles = entries.filter((f) => f.endsWith(".json"));
+        const workflows = [];
+        for (const file of jsonFiles) {
+          const content = await readFile(join(dir, file), "utf-8");
+          workflows.push(JSON.parse(content));
+        }
+        return workflows;
+      } catch {
+        return [];
+      }
+    }
+  };
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/workflow.d.ts

@@ -0,0 +1,52 @@
+export interface WorkflowStateDefinition {
+    slug: string;
+    name: string;
+    color: string;
+    category: 'start' | 'in-progress' | 'end';
+}
+export declare const Directions: {
+    readonly FORWARD: "forward";
+    readonly BACKWARD: "backward";
+    readonly OTHER: "other";
+};
+export type Direction = (typeof Directions)[keyof typeof Directions];
+export type TransitionHandler = {
+    name: string;
+    params?: Record<string, unknown>;
+};
+export type TransitionHandlerParams = Record<string, unknown> | undefined;
+export type StateArgs = Record<string, unknown> & {
+    transition: TransitionRule;
+};
+export interface TransitionHandlerDefinition {
+    name: string;
+    friendlyName: string;
+    description?: string;
+    run: (params: TransitionHandlerParams, args: StateArgs) => Promise<boolean | Record<string, unknown> | undefined>;
+    global?: boolean;
+}
+export interface TransitionRule<TConditions extends Record<string, unknown> = Record<string, unknown>> {
+    from: string | 'all';
+    to: string;
+    direction: Direction;
+    handler?: TransitionHandler[];
+    conditions?: TConditions;
+}
+export interface Workflow<TConditions extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    states: WorkflowStateDefinition[];
+    transitions: TransitionRule<TConditions>[];
+}
+export interface WorkflowProvider {
+    getWorkflow: (name: string) => Promise<Workflow>;
+    listWorkflows: () => Promise<Workflow[]>;
+    saveWorkflow?: (workflow: Workflow) => Promise<Workflow>;
+    deleteWorkflow?: (name: string) => Promise<void>;
+}
+export type TransitionConditionFilter<TConditions extends Record<string, unknown> = Record<string, unknown>> = (rule: TransitionRule<TConditions>, context: Record<string, unknown>) => boolean;
+export declare class TransitionHandlerError extends Error {
+    options: Record<string, unknown>;
+    constructor(message: string, options?: Record<string, unknown>);
+}
+export declare function defineTransitionHandler(def: TransitionHandlerDefinition): TransitionHandlerDefinition;

package/dist/runtime/workflow.js

@@ -0,0 +1,16 @@
+export const Directions = {
+  FORWARD: "forward",
+  BACKWARD: "backward",
+  OTHER: "other"
+};
+export class TransitionHandlerError extends Error {
+  options;
+  constructor(message, options) {
+    super(message);
+    this.name = "TransitionHandlerError";
+    this.options = options ?? {};
+  }
+}
+export function defineTransitionHandler(def) {
+  return def;
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "ablauf",
+  "version": "0.0.1",
+  "description": "Workflow engine for Nuxt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niki2k1/ablauf.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./runtime/workflow": {
+      "types": "./src/runtime/workflow.ts",
+      "import": "./src/runtime/workflow.ts",
+      "default": "./src/runtime/workflow.ts"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src/runtime"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "typecheck": "vue-tsc --noEmit",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.3.0",
+    "consola": "^3.4.2"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.13.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.0",
+    "@nuxt/test-utils": "^3.23.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.2",
+    "nuxt": "^4.3.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4"
+  },
+  "packageManager": "pnpm@9.15.5+sha512.845196026aab1cc3f098a0474b64dfbab2afe7a1b4e91dd86895d8e4aa32a7a6d03049e2d0ad770bbe4de023a7122fb68c1a1d6e0d033c7076085f9d5d4800d4"
+}

package/src/runtime/composables/useWorkflow.ts

@@ -0,0 +1,129 @@
+import type {
+  Direction,
+  StateArgs,
+  TransitionConditionFilter,
+  TransitionRule,
+  Workflow,
+  WorkflowStateDefinition,
+} from 'ablauf/runtime/workflow'
+import {
+  runGlobalTransitionHandlers,
+  runTransitionHandler,
+} from '../handler'
+
+export interface UseWorkflowOptions<
+  TConditions extends Record<string, unknown> = Record<string, unknown>,
+> {
+  conditionFilter?: TransitionConditionFilter<TConditions>
+}
+
+export async function useWorkflow<
+  TConditions extends Record<string, unknown> = Record<string, unknown>,
+>(name: string, options?: UseWorkflowOptions<TConditions>) {
+  const workflow = await $fetch<Workflow<TConditions>>(
+    `/api/_workflow/${name}`,
+  )
+
+  if (!workflow) {
+    throw new Error(`Workflow "${name}" not found`)
+  }
+
+  function getStates(): WorkflowStateDefinition[] {
+    return workflow.states
+  }
+
+  function getState(slug: string): WorkflowStateDefinition | undefined {
+    return workflow.states.find((s) => s.slug === slug)
+  }
+
+  function getStateColor(slug: string): string {
+    return getState(slug)?.color ?? '#9E9E9E'
+  }
+
+  function getNextStates(
+    currentState: string,
+    direction: Direction,
+    context?: Record<string, unknown>,
+  ): string[] {
+    const stateDef = getState(currentState)
+    if (stateDef?.category === 'end') {
+      return []
+    }
+
+    return workflow.transitions
+      .filter((rule) => {
+        if (rule.from === 'all') {
+          return currentState !== rule.to && rule.direction === direction
+        }
+        return rule.from === currentState && rule.direction === direction
+      })
+      .filter((rule) => {
+        if (!options?.conditionFilter || !context) return true
+        return options.conditionFilter(rule, context)
+      })
+      .map((rule) => rule.to)
+  }
+
+  function findTransition(
+    from: string,
+    to: string,
+  ): TransitionRule<TConditions> | undefined {
+    return workflow.transitions.find(
+      (rule) =>
+        (rule.from === from || rule.from === 'all') && rule.to === to,
+    )
+  }
+
+  async function transition(
+    currentState: string,
+    newState: string,
+    args: Record<string, unknown>,
+  ): Promise<TransitionRule<TConditions> | false> {
+    if (currentState === newState) {
+      return false
+    }
+
+    const rule = findTransition(currentState, newState)
+    if (!rule) {
+      throw new Error(
+        `No transition from "${currentState}" to "${newState}"`,
+      )
+    }
+
+    const fullArgs: StateArgs = { ...args, transition: rule }
+
+    // Run global transition handlers first
+    await runGlobalTransitionHandlers(fullArgs)
+
+    // Run per-transition handlers
+    if (rule.handler) {
+      for (const h of rule.handler) {
+        const result = await runTransitionHandler({
+          name: h.name,
+          params: h.params,
+          args: fullArgs,
+        })
+
+        if (typeof result === 'boolean' && result === false) {
+          return false
+        }
+
+        if (typeof result === 'object' && result !== null) {
+          Object.assign(fullArgs, result)
+        }
+      }
+    }
+
+    return rule
+  }
+
+  return {
+    workflow,
+    getStates,
+    getState,
+    getStateColor,
+    getNextStates,
+    findTransition,
+    transition,
+  }
+}

package/src/runtime/handler.ts

@@ -0,0 +1,40 @@
+import type {
+  TransitionHandlerDefinition,
+  TransitionHandlerParams,
+  StateArgs,
+} from 'ablauf/runtime/workflow'
+// @ts-expect-error virtual module generated by ablauf
+import { getAllTransitions } from '#transitions'
+
+export function getTransitionHandler(
+  name: string,
+): TransitionHandlerDefinition | undefined {
+  const transitions = getAllTransitions() as TransitionHandlerDefinition[]
+  return transitions.find((t) => t.name === name)
+}
+
+export function getGlobalTransitionHandlers(): TransitionHandlerDefinition[] {
+  const transitions = getAllTransitions() as TransitionHandlerDefinition[]
+  return transitions.filter((t) => t.global)
+}
+
+export async function runTransitionHandler(options: {
+  name: string
+  params: TransitionHandlerParams
+  args: StateArgs
+}): Promise<boolean | Record<string, unknown> | undefined> {
+  const handler = getTransitionHandler(options.name)
+  if (!handler) {
+    throw new Error(`Transition handler "${options.name}" not found`)
+  }
+  return handler.run(options.params, options.args)
+}
+
+export async function runGlobalTransitionHandlers(
+  args: StateArgs,
+): Promise<void> {
+  const globalHandlers = getGlobalTransitionHandlers()
+  for (const handler of globalHandlers) {
+    await runTransitionHandler({ name: handler.name, params: {}, args })
+  }
+}

package/src/runtime/server/api/workflows/[name].get.ts

@@ -0,0 +1,20 @@
+import { defineEventHandler, getRouterParam, createError } from 'h3'
+import { useWorkflowProvider } from '../../provider'
+
+export default defineEventHandler(async (event) => {
+  const name = getRouterParam(event, 'name')
+  if (!name) {
+    throw createError({ statusCode: 400, message: 'Workflow name is required' })
+  }
+
+  const provider = useWorkflowProvider()
+
+  try {
+    return await provider.getWorkflow(name)
+  } catch {
+    throw createError({
+      statusCode: 404,
+      message: `Workflow "${name}" not found`,
+    })
+  }
+})

package/src/runtime/server/api/workflows/index.get.ts

@@ -0,0 +1,7 @@
+import { defineEventHandler } from 'h3'
+import { useWorkflowProvider } from '../../provider'
+
+export default defineEventHandler(async () => {
+  const provider = useWorkflowProvider()
+  return provider.listWorkflows()
+})

package/src/runtime/server/plugins/workflow-provider.ts

@@ -0,0 +1,10 @@
+import { defineNitroPlugin } from 'nitropack/runtime'
+import { createFileWorkflowProvider } from '../providers/file.js'
+import { setWorkflowProvider } from '../provider.js'
+
+// @ts-expect-error virtual module injected by ablauf
+import { workflowsDir } from '#ablauf-options'
+
+export default defineNitroPlugin(() => {
+  setWorkflowProvider(createFileWorkflowProvider(workflowsDir))
+})

package/src/runtime/server/provider.ts

@@ -0,0 +1,16 @@
+import type { WorkflowProvider } from 'ablauf/runtime/workflow'
+
+let _provider: WorkflowProvider | null = null
+
+export function setWorkflowProvider(provider: WorkflowProvider) {
+  _provider = provider
+}
+
+export function useWorkflowProvider(): WorkflowProvider {
+  if (!_provider) {
+    throw new Error(
+      'No workflow provider configured. Call setWorkflowProvider() in a Nitro plugin or set provider option in module config.',
+    )
+  }
+  return _provider
+}

package/src/runtime/server/providers/file.ts

@@ -0,0 +1,33 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Workflow, WorkflowProvider } from 'ablauf/runtime/workflow'
+
+export function createFileWorkflowProvider(dir: string): WorkflowProvider {
+  return {
+    async getWorkflow(name: string): Promise<Workflow> {
+      const filePath = join(dir, `${name}.json`)
+      try {
+        const content = await readFile(filePath, 'utf-8')
+        return JSON.parse(content) as Workflow
+      } catch {
+        throw new Error(`Workflow "${name}" not found at ${filePath}`)
+      }
+    },
+
+    async listWorkflows(): Promise<Workflow[]> {
+      try {
+        const entries = await readdir(dir)
+        const jsonFiles = entries.filter((f) => f.endsWith('.json'))
+
+        const workflows: Workflow[] = []
+        for (const file of jsonFiles) {
+          const content = await readFile(join(dir, file), 'utf-8')
+          workflows.push(JSON.parse(content) as Workflow)
+        }
+        return workflows
+      } catch {
+        return []
+      }
+    },
+  }
+}

package/src/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/src/runtime/workflow.ts

@@ -0,0 +1,101 @@
+// --- States ---
+
+export interface WorkflowStateDefinition {
+  slug: string
+  name: string
+  color: string
+  category: 'start' | 'in-progress' | 'end'
+}
+
+// --- Directions ---
+
+export const Directions = {
+  FORWARD: 'forward',
+  BACKWARD: 'backward',
+  OTHER: 'other',
+} as const
+
+export type Direction = (typeof Directions)[keyof typeof Directions]
+
+// --- Transition Handlers ---
+
+export type TransitionHandler = {
+  name: string
+  params?: Record<string, unknown>
+}
+
+export type TransitionHandlerParams = Record<string, unknown> | undefined
+
+export type StateArgs = Record<string, unknown> & {
+  transition: TransitionRule
+}
+
+export interface TransitionHandlerDefinition {
+  name: string
+  friendlyName: string
+  description?: string
+  run: (
+    params: TransitionHandlerParams,
+    args: StateArgs,
+  ) => Promise<boolean | Record<string, unknown> | undefined>
+  global?: boolean
+}
+
+// --- Transition Rules ---
+
+export interface TransitionRule<
+  TConditions extends Record<string, unknown> = Record<string, unknown>,
+> {
+  from: string | 'all'
+  to: string
+  direction: Direction
+  handler?: TransitionHandler[]
+  conditions?: TConditions
+}
+
+// --- Workflow ---
+
+export interface Workflow<
+  TConditions extends Record<string, unknown> = Record<string, unknown>,
+> {
+  name: string
+  description?: string
+  states: WorkflowStateDefinition[]
+  transitions: TransitionRule<TConditions>[]
+}
+
+// --- Workflow Provider ---
+
+export interface WorkflowProvider {
+  getWorkflow: (name: string) => Promise<Workflow>
+  listWorkflows: () => Promise<Workflow[]>
+  saveWorkflow?: (workflow: Workflow) => Promise<Workflow>
+  deleteWorkflow?: (name: string) => Promise<void>
+}
+
+// --- Condition Filter ---
+
+export type TransitionConditionFilter<
+  TConditions extends Record<string, unknown> = Record<string, unknown>,
+> = (
+  rule: TransitionRule<TConditions>,
+  context: Record<string, unknown>,
+) => boolean
+
+// --- Errors ---
+
+export class TransitionHandlerError extends Error {
+  options: Record<string, unknown>
+
+  constructor(message: string, options?: Record<string, unknown>) {
+    super(message)
+    this.name = 'TransitionHandlerError'
+    this.options = options ?? {}
+  }
+}
+
+// --- Utilities ---
+
+export function defineTransitionHandler(def: TransitionHandlerDefinition) {
+  return def
+}