@moostjs/event-wf 0.6.5 → 0.6.7

package/dist/index.cjs

@@ -239,6 +239,7 @@ const CONTEXT_TYPE = "WF";
 				resolveArgs: opts.resolveArgs,
 				manualUnscope: true,
 				targetPath,
+				controllerPrefix: opts.prefix,
 				handlerType: handler.type
 			});
 			if (handler.type === "WF_STEP") {
@@ -262,7 +263,7 @@ const CONTEXT_TYPE = "WF";
 				let wfSchema = mate.read(opts.fakeInstance, opts.method)?.wfSchema;
 				if (!wfSchema) wfSchema = mate.read(opts.fakeInstance)?.wfSchema;
 				const _fn = async () => {
-					(0, moost.setControllerContext)(this.moost, "bindHandler", targetPath);
+					(0, moost.setControllerContext)(this.moost, "bindHandler", targetPath, { prefix: opts.prefix });
 					return fn();
 				};
 				this.toInit.push(() => {

package/dist/index.mjs

@@ -216,6 +216,7 @@ const CONTEXT_TYPE = "WF";
 				resolveArgs: opts.resolveArgs,
 				manualUnscope: true,
 				targetPath,
+				controllerPrefix: opts.prefix,
 				handlerType: handler.type
 			});
 			if (handler.type === "WF_STEP") {
@@ -239,7 +240,7 @@ const CONTEXT_TYPE = "WF";
 				let wfSchema = mate.read(opts.fakeInstance, opts.method)?.wfSchema;
 				if (!wfSchema) wfSchema = mate.read(opts.fakeInstance)?.wfSchema;
 				const _fn = async () => {
-					setControllerContext(this.moost, "bindHandler", targetPath);
+					setControllerContext(this.moost, "bindHandler", targetPath, { prefix: opts.prefix });
 					return fn();
 				};
 				this.toInit.push(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-wf",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "@moostjs/event-wf",
   "keywords": [
     "composables",
@@ -21,13 +21,8 @@
     "url": "git+https://github.com/moostjs/moostjs.git",
     "directory": "packages/event-wf"
   },
-  "bin": {
-    "moostjs-event-wf-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
@@ -44,7 +39,7 @@
   },
   "dependencies": {
     "@prostojs/wf": "^0.1.1",
-    "@wooksjs/event-wf": "^0.7.8"
+    "@wooksjs/event-wf": "^0.7.9"
   },
   "devDependencies": {
     "vitest": "3.2.4"
@@ -52,13 +47,12 @@
   "peerDependencies": {
     "@prostojs/infact": "^0.4.1",
     "@prostojs/mate": "^0.4.0",
-    "@wooksjs/event-core": "^0.7.8",
-    "wooks": "^0.7.8",
-    "moost": "^0.6.5"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9",
+    "moost": "^0.6.7"
   },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "test": "vitest"
   }
 }

package/scripts/setup-skills.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'moostjs-event-wf'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/moostjs-event-wf/SKILL.md

@@ -1,40 +0,0 @@
----
-name: moostjs-event-wf
-description: Use this skill when working with @moostjs/event-wf — to define workflow steps with @Step(), create workflow entry points with @Workflow() and @WorkflowSchema(), inject workflow data with @WorkflowParam(), set up MoostWf adapter, start and resume workflows with wf.start()/wf.resume(), handle pause/resume with inputRequired, use StepRetriableError for recoverable failures, observe execution with attachSpy(), access workflow state with useWfState(), build conditional and looping schemas, integrate workflows with HTTP/CLI handlers, or use wfKind for event-type-aware logic.
----
-
-# @moostjs/event-wf
-
-Workflow event adapter for Moost, wrapping `@wooksjs/event-wf` and `@prostojs/wf`. Define workflow steps and flows using decorators, with full Moost DI, interceptors, and pipes.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain | File | Load when... |
-|--------|------|------------|
-| Core concepts & setup | [core.md](core.md) | Starting a new project, installing the package, understanding the mental model, configuring MoostWf |
-| Decorators & composables | [decorators.md](decorators.md) | Using @Step, @Workflow, @WorkflowSchema, @WorkflowParam, useWfState(), wfKind |
-| Schemas & flow control | [schemas.md](schemas.md) | Defining step sequences, conditions, loops, break/continue, nested sub-workflows |
-| Execution & lifecycle | [execution.md](execution.md) | Starting/resuming workflows, reading TFlowOutput, pause/resume, StepRetriableError, spies |
-| Integration | [integration.md](integration.md) | Triggering workflows from HTTP/CLI, using interceptors/pipes/DI in steps, multi-adapter setup |
-
-## Quick reference
-
-```ts
-import {
-  MoostWf, Step, Workflow, WorkflowSchema, WorkflowParam,
-  StepRetriableError, useWfState, wfKind,
-} from '@moostjs/event-wf'
-
-// Register adapter
-const wf = new MoostWf()
-app.adapter(wf)
-
-// Start / resume
-const result = await wf.start('schema-id', initialContext, input?)
-const resumed = await wf.resume(result.state, newInput)
-
-// Observe
-const detach = wf.attachSpy((event, output, flow, ms) => { ... })
-```

package/skills/moostjs-event-wf/core.md

@@ -1,138 +0,0 @@
-# Core Concepts & Setup — @moostjs/event-wf
-
-> Installation, mental model, adapter configuration, and getting started with Moost workflows.
-
-## Concepts
-
-Moost Workflows model multi-step processes as composable, typed sequences of operations. The key abstractions:
-
-- **Steps** — Individual units of work. Controller methods decorated with `@Step` that read/write shared context.
-- **Schemas** — Declarative arrays defining execution order, conditions, and loops.
-- **Context** — A typed object that holds shared state across all steps in a workflow.
-- **MoostWf** — The adapter class that bridges `@wooksjs/event-wf` into Moost's decorator/DI system.
-- **TFlowOutput** — The result object from `start()`/`resume()` containing state, completion status, and resume functions.
-
-Workflows are a good fit when your process has multiple stages, needs branching, can be interrupted for external input, requires auditability, or spans time.
-
-## Installation
-
-```bash
-npm install @moostjs/event-wf
-# or
-pnpm add @moostjs/event-wf
-```
-
-Peer dependencies: `moost`, `@wooksjs/event-core`, `@prostojs/infact`, `@prostojs/mate`, `wooks`.
-
-## Getting Started
-
-### 1. Define a workflow controller
-
-```ts
-import { Controller, Injectable } from 'moost'
-import { Step, Workflow, WorkflowParam, WorkflowSchema } from '@moostjs/event-wf'
-
-interface TOrderContext {
-  orderId: string
-  validated: boolean
-  charged: boolean
-  shipped: boolean
-}
-
-@Injectable('FOR_EVENT')
-@Controller()
-export class OrderController {
-  @WorkflowParam('context')
-  ctx!: TOrderContext
-
-  @Workflow('process-order')
-  @WorkflowSchema<TOrderContext>(['validate', 'charge', 'ship'])
-  processOrder() {}
-
-  @Step('validate')
-  validate() {
-    this.ctx.validated = true
-  }
-
-  @Step('charge')
-  charge() {
-    this.ctx.charged = true
-  }
-
-  @Step('ship')
-  ship() {
-    this.ctx.shipped = true
-  }
-}
-```
-
-### 2. Register the adapter and start
-
-```ts
-import { Moost } from 'moost'
-import { MoostWf } from '@moostjs/event-wf'
-import { OrderController } from './order.controller'
-
-const app = new Moost()
-const wf = new MoostWf()
-
-app.adapter(wf)
-app.registerControllers(OrderController)
-await app.init()
-
-const result = await wf.start('process-order', {
-  orderId: 'ORD-001',
-  validated: false,
-  charged: false,
-  shipped: false,
-})
-
-console.log(result.finished) // true
-console.log(result.state.context)
-// { orderId: 'ORD-001', validated: true, charged: true, shipped: true }
-```
-
-## MoostWf Constructor
-
-```ts
-new MoostWf<T, IR>(opts?: WooksWf<T, IR> | TWooksWfOptions, debug?: boolean)
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `opts` | `WooksWf \| TWooksWfOptions \| undefined` | Pre-existing WooksWf instance, config options, or undefined for defaults |
-| `debug` | `boolean` | Enable error logging |
-
-**TWooksWfOptions fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `onError` | `(e: Error) => void` | Global error handler |
-| `onNotFound` | `TWooksHandler` | Handler for unregistered steps |
-| `onUnknownFlow` | `(schemaId: string, raiseError: () => void) => unknown` | Handler for unknown workflow schemas |
-| `logger` | `TConsoleBase` | Custom logger instance |
-| `eventOptions` | `EventContextOptions` | Event context configuration |
-| `router` | `TWooksOptions['router']` | Router configuration |
-
-You can also pass an existing `WooksWf` instance to share the workflow engine with non-Moost code:
-
-```ts
-const wooksWf = createWfApp()
-const wf = new MoostWf(wooksWf)
-```
-
-## Lifecycle Overview
-
-1. `app.adapter(wf)` registers the adapter
-2. `app.registerControllers(...)` registers controllers
-3. `app.init()` processes decorators and binds `@Step`/`@Workflow` handlers
-4. `wf.start(schemaId, context)` starts workflow execution
-5. Steps execute in sequence, reading/mutating shared context
-6. Workflow completes or pauses (if a step needs input)
-
-## Best Practices
-
-- Use `@Injectable('FOR_EVENT')` on workflow controllers to get fresh instances per step execution. Without it, the controller is a singleton — class properties would be shared across concurrent workflows.
-- Keep the `@Workflow` entry point method body empty — all logic belongs in steps.
-- Define a TypeScript interface for your context type and pass it as a generic to `@WorkflowSchema<T>()` for type-safe conditions.
-- The workflow `state` object is plain JSON — you can serialize and store it for later resumption.

package/skills/moostjs-event-wf/decorators.md

@@ -1,179 +0,0 @@
-# Decorators & Composables — @moostjs/event-wf
-
-> All decorators and composables exported by @moostjs/event-wf for defining and accessing workflow handlers.
-
-## API Reference
-
-### `@Step(path?)`
-
-Marks a controller method as a workflow step handler.
-
-- **`path`** *(string, optional)* — Step identifier used in schemas. Defaults to the method name.
-
-```ts
-import { Step, WorkflowParam } from '@moostjs/event-wf'
-
-@Step('validate')
-validate(@WorkflowParam('context') ctx: TOrderContext) {
-  ctx.validated = true
-}
-```
-
-Steps can have parametric paths (like HTTP routes):
-
-```ts
-import { Param } from 'moost'
-
-@Step('notify/:channel(email|sms)')
-notify(@Param('channel') channel: 'email' | 'sms') {
-  // Reference in schema: { id: 'notify/email' }
-}
-```
-
-### `@Workflow(path?)`
-
-Marks a controller method as a workflow entry point. Must be paired with `@WorkflowSchema`.
-
-- **`path`** *(string, optional)* — Workflow identifier. Defaults to the method name.
-
-The effective schema ID combines the controller prefix and the workflow path. For `@Controller('admin')` + `@Workflow('order')`, the schema ID is `admin/order`.
-
-```ts
-@Workflow('order-processing')
-@WorkflowSchema<TOrderContext>(['validate', 'charge', 'ship'])
-processOrder() {}
-```
-
-### `@WorkflowSchema<T>(schema)`
-
-Attaches a workflow schema (step sequence) to a `@Workflow` method.
-
-- **`T`** *(generic)* — Workflow context type for type-checked conditions.
-- **`schema`** *(`TWorkflowSchema<T>`)* — Array of step definitions.
-
-```ts
-@WorkflowSchema<TMyContext>([
-  'step-a',
-  { condition: (ctx) => ctx.ready, id: 'step-b' },
-  { while: 'retries < 3', steps: ['attempt', 'increment'] },
-])
-```
-
-See [schemas.md](schemas.md) for full schema syntax.
-
-### `WorkflowParam(name)`
-
-Parameter and property decorator that injects workflow runtime values.
-
-| Name | Type | Description |
-|------|------|-------------|
-| `'context'` | `T` | Shared workflow context object |
-| `'input'` | `I \| undefined` | Input passed to `start()` or `resume()` |
-| `'stepId'` | `string \| null` | Current step ID (`null` in entry point) |
-| `'schemaId'` | `string` | Active workflow schema identifier |
-| `'indexes'` | `number[] \| undefined` | Current position in nested schemas |
-| `'resume'` | `boolean` | `true` when resuming, `false` on first run |
-| `'state'` | `object` | Full state object from `useWfState()` |
-
-**As method parameter:**
-
-```ts
-@Step('process')
-process(
-  @WorkflowParam('context') ctx: TMyContext,
-  @WorkflowParam('input') input: TMyInput | undefined,
-  @WorkflowParam('resume') isResume: boolean,
-) {
-  if (isResume) {
-    console.log('Resuming with new input:', input)
-  }
-  ctx.processed = true
-}
-```
-
-**As class property** (requires `@Injectable('FOR_EVENT')`):
-
-```ts
-@Injectable('FOR_EVENT')
-@Controller()
-export class MyController {
-  @WorkflowParam('context')
-  ctx!: TMyContext
-
-  @Step('review')
-  review() {
-    this.ctx.status = 'reviewed'
-  }
-}
-```
-
-### `useWfState()`
-
-Composable that returns the current workflow execution state. Available inside step and entry point handlers.
-
-```ts
-import { useWfState } from '@moostjs/event-wf'
-
-const state = useWfState()
-state.ctx<TMyContext>()     // workflow context
-state.input<TMyInput>()    // step input (or undefined)
-state.schemaId             // workflow schema ID
-state.stepId()             // current step ID (or null)
-state.indexes              // position in nested schemas
-state.resume               // boolean: is this a resume?
-```
-
-In most cases, prefer `@WorkflowParam` decorators. The composable is useful for advanced scenarios like custom interceptors or utilities that need workflow context.
-
-### `wfKind`
-
-Event kind marker for workflow events. Used internally by the adapter and useful for building custom event-type-aware logic.
-
-```ts
-import { wfKind } from '@moostjs/event-wf'
-```
-
-## Common Patterns
-
-### Pattern: Class Property Injection
-
-When using `@Injectable('FOR_EVENT')`, inject context as a class property. Multiple steps in the same controller share the property declaration but get separate instances per execution.
-
-```ts
-@Injectable('FOR_EVENT')
-@Controller()
-export class OnboardingController {
-  @WorkflowParam('context')
-  ctx!: TOnboardingContext
-
-  @Step('verify-email')
-  verifyEmail() { this.ctx.emailVerified = true }
-
-  @Step('collect-profile')
-  collectProfile() { this.ctx.profileComplete = true }
-}
-```
-
-### Pattern: Reusing Steps Across Workflows
-
-Steps are resolved by their path through the Wooks router. Any workflow schema can reference any registered step:
-
-```ts
-@Controller()
-export class SharedSteps {
-  @Step('send-notification')
-  sendNotification(@WorkflowParam('context') ctx: { email: string, message: string }) {
-    sendEmail(ctx.email, ctx.message)
-  }
-}
-
-// Referenced from multiple schemas:
-@WorkflowSchema(['validate', 'process', 'send-notification'])
-@WorkflowSchema(['review', 'approve', 'send-notification'])
-```
-
-## Gotchas
-
-- `WorkflowParam('resume')` returns a **boolean**, not a function. It indicates whether the current execution is a resume. The resume *function* is on the `TFlowOutput` object returned by `start()` or `resume()`.
-- Without `@Injectable('FOR_EVENT')`, the controller is a singleton. Using class property injection in a singleton causes state to leak between concurrent workflows — use method parameters instead.
-- If you omit the `path` argument from `@Step()` or `@Workflow()`, the method name is used as the identifier.

package/skills/moostjs-event-wf/execution.md

@@ -1,325 +0,0 @@
-# Execution & Lifecycle — @moostjs/event-wf
-
-> Starting and resuming workflows, reading output, pause/resume patterns, error handling, and spies.
-
-## Concepts
-
-Workflows execute via `wf.start()` and produce a `TFlowOutput` describing the result. A workflow can complete, pause for input, or fail. Paused workflows can be resumed from serialized state. Spies observe execution in real time.
-
-## API Reference
-
-### `wf.start<I>(schemaId, initialContext, input?)`
-
-Starts a new workflow execution.
-
-```ts
-start<I>(
-  schemaId: string,
-  initialContext: T,
-  input?: I,
-): Promise<TFlowOutput<T, I, IR>>
-```
-
-| Parameter | Description |
-|-----------|-------------|
-| `schemaId` | Workflow identifier (matching `@Workflow` path, including controller prefix) |
-| `initialContext` | Initial context object passed to steps |
-| `input` | Optional input for the first step |
-
-```ts
-const result = await wf.start('process-order', {
-  orderId: '123',
-  status: 'new',
-})
-```
-
-### `wf.resume<I>(state, input?)`
-
-Resumes a paused workflow from a saved state.
-
-```ts
-resume<I>(
-  state: { schemaId: string, context: T, indexes: number[] },
-  input?: I,
-): Promise<TFlowOutput<T, I, IR>>
-```
-
-| Parameter | Description |
-|-----------|-------------|
-| `state` | State object from a previous `TFlowOutput.state` |
-| `input` | Input for the paused step |
-
-```ts
-const resumed = await wf.resume(previousResult.state, { answer: 'yes' })
-```
-
-### `wf.attachSpy<I>(fn)`
-
-Attaches a spy function to observe workflow execution. Returns a detach function.
-
-```ts
-const detach = wf.attachSpy((event, eventOutput, flowOutput, ms) => {
-  console.log(event, flowOutput.stepId, ms)
-})
-detach() // stop observing
-```
-
-### `wf.detachSpy<I>(fn)`
-
-Removes a previously attached spy function.
-
-### `wf.getWfApp()`
-
-Returns the underlying `WooksWf` instance for advanced low-level access.
-
-## TFlowOutput
-
-Returned by `start()` and `resume()`. Describes the workflow's current state.
-
-```ts
-interface TFlowOutput<T, I, IR> {
-  state: {
-    schemaId: string      // workflow identifier
-    context: T            // current context (with all mutations)
-    indexes: number[]     // position in schema (for resume)
-  }
-  finished: boolean       // true if workflow completed all steps
-  stepId: string          // last executed step ID
-  inputRequired?: IR      // present when a step needs input
-  interrupt?: boolean     // true when paused (input or retriable error)
-  break?: boolean         // true if a break condition ended the flow
-  resume?: (input: I) => Promise<TFlowOutput<T, unknown, IR>>
-  retry?: (input?: I) => Promise<TFlowOutput<T, unknown, IR>>
-  error?: Error           // error if step threw
-  errorList?: unknown     // structured error details from StepRetriableError
-  expires?: number        // TTL in ms (if set by the step)
-}
-```
-
-Key interpretation:
-- `finished: true` — workflow completed all steps
-- `finished: false` + `interrupt: true` — workflow is paused (input needed or retriable error)
-- `finished: true` + `error` — workflow failed with an unrecoverable error
-
-## Pause & Resume
-
-### Pausing a Workflow
-
-A step pauses the workflow by returning an object with `inputRequired`:
-
-```ts
-@Step('collect-address')
-collectAddress(
-  @WorkflowParam('input') input?: TAddress,
-  @WorkflowParam('context') ctx: TRegistrationContext,
-) {
-  if (!input) {
-    return { inputRequired: true }  // pauses the workflow
-  }
-  ctx.address = input
-}
-```
-
-The `inputRequired` value can be anything — a boolean, a form schema, a structured object. Moost passes it through without interpretation.
-
-### Reading Paused Output
-
-```ts
-const result = await wf.start('registration', initialContext)
-
-if (!result.finished) {
-  console.log(result.interrupt)      // true
-  console.log(result.inputRequired)  // whatever the step returned
-  console.log(result.stepId)         // 'collect-address'
-  console.log(result.state)          // serializable state
-}
-```
-
-### Resuming with Convenience Function
-
-```ts
-if (result.inputRequired && result.resume) {
-  const resumed = await result.resume({ street: '123 Main St', city: 'Springfield' })
-}
-```
-
-### Resuming from Stored State
-
-For workflows that span time, serialize the state and resume later:
-
-```ts
-// Store
-await db.save('pending', { state: result.state, inputRequired: result.inputRequired })
-
-// Later, resume
-const saved = await db.load('pending', workflowId)
-const resumed = await wf.resume(saved.state, userInput)
-```
-
-### Multi-Step Pause/Resume
-
-A workflow can pause and resume multiple times:
-
-```ts
-let result = await wf.start('registration', emptyContext)
-result = await wf.resume(result.state, { name: 'Alice' })
-result = await wf.resume(result.state, { email: 'alice@example.com' })
-result = await wf.resume(result.state, { street: '123 Main' })
-console.log(result.finished) // true
-```
-
-### Expiration
-
-Steps can set an expiration time (in milliseconds) for paused state:
-
-```ts
-@Step('collect-payment')
-collectPayment(@WorkflowParam('input') input?: TPayment) {
-  if (!input) {
-    return { inputRequired: { type: 'payment-form' }, expires: 15 * 60 * 1000 }
-  }
-}
-```
-
-The workflow engine does not enforce expiration — it provides the value for your application to check.
-
-## Error Handling
-
-### Regular Errors
-
-Throwing a standard error fails the workflow immediately:
-
-```ts
-@Step('validate')
-validate(@WorkflowParam('context') ctx: TCtx) {
-  if (!ctx.paymentMethodId) throw new Error('No payment method')
-}
-// Output: { finished: true, error: Error(...) } — no resume/retry available
-```
-
-### StepRetriableError
-
-Signals a recoverable failure. The workflow pauses instead of failing:
-
-```ts
-import { StepRetriableError } from '@moostjs/event-wf'
-
-@Step('charge-card')
-chargeCard(@WorkflowParam('input') input?: TPaymentInput) {
-  try {
-    processPayment(input)
-  } catch (e) {
-    throw new StepRetriableError(
-      e as Error,                                              // original error
-      [{ code: 'CARD_DECLINED', message: 'Card declined' }],  // errorList
-      { type: 'payment-form', hint: 'Try a different card' }, // inputRequired
-    )
-  }
-}
-```
-
-**Constructor:**
-
-```ts
-new StepRetriableError(
-  originalError: Error,       // the underlying error
-  errorList?: unknown,        // structured error details (any shape)
-  inputRequired?: IR,         // what input is needed to retry
-  expires?: number,           // optional TTL in ms
-)
-```
-
-**Retriable output:**
-
-```ts
-{
-  finished: false,       // not done — can be retried
-  interrupt: true,       // execution paused
-  error: Error('...'),
-  errorList: [...],
-  inputRequired: { ... },
-  retry: [Function],     // retry from the same step
-  resume: [Function],    // same as retry for retriable errors
-  state: { ... },
-}
-```
-
-**Retrying:**
-
-```ts
-const result = await wf.start('payment', paymentContext)
-if (result.error && result.retry) {
-  const retried = await result.retry(newPaymentInput)
-}
-// Or from stored state:
-const retried = await wf.resume(result.state, newInput)
-```
-
-### When to Use Which
-
-| Scenario | Approach |
-|----------|----------|
-| Invalid configuration, programming bug | `throw new Error(...)` |
-| External service temporarily unavailable | `throw new StepRetriableError(...)` |
-| User input fails validation | `StepRetriableError` with `errorList` and `inputRequired` |
-| Rate limit hit | `StepRetriableError` with `expires` |
-
-## Spies & Observability
-
-### Attaching a Spy
-
-```ts
-const detach = wf.attachSpy((event, eventOutput, flowOutput, ms) => {
-  console.log(`[${event}] step=${flowOutput.stepId} (${ms}ms)`)
-})
-```
-
-### Spy Callback Signature
-
-```ts
-type TWorkflowSpy<T, I, IR> = (
-  event: string,
-  eventOutput: string | undefined | { fn: string | Function, result: boolean },
-  flowOutput: TFlowOutput<T, I, IR>,
-  ms?: number,
-) => void
-```
-
-### Spy Events
-
-| Event | When | eventOutput |
-|-------|------|-------------|
-| `'workflow-start'` | Workflow begins | `undefined` |
-| `'subflow-start'` | Nested sub-workflow begins | `undefined` |
-| `'step'` | A step finishes executing | Step ID (string) |
-| `'eval-condition-fn'` | Step condition evaluated | `{ fn, result }` |
-| `'eval-while-cond'` | Loop condition evaluated | `{ fn, result }` |
-| `'eval-break-fn'` | Break condition evaluated | `{ fn, result }` |
-| `'eval-continue-fn'` | Continue condition evaluated | `{ fn, result }` |
-| `'workflow-end'` | Workflow completes | `undefined` |
-| `'workflow-interrupt'` | Workflow pauses | `undefined` |
-| `'subflow-end'` | Sub-workflow completes | `undefined` |
-
-### Detaching
-
-```ts
-// Option 1: returned function
-const detach = wf.attachSpy(mySpy)
-detach()
-
-// Option 2: explicit
-wf.detachSpy(mySpy)
-```
-
-## Best Practices
-
-- A `retry()` or `resume()` call re-executes only the paused/failed step and continues — it does not re-run previously completed steps.
-- Keep spy callbacks lightweight — they run synchronously during execution. Buffer heavy processing.
-- The `state` object is plain JSON — safe for serialization, database storage, and API responses.
-- Type the `MoostWf` instance generically (`MoostWf<TMyContext>`) to get typed output.
-
-## Gotchas
-
-- `finished: true` with an `error` means unrecoverable failure (regular `throw`). `finished: false` with `error` means retriable (`StepRetriableError`).
-- The `expires` field is informational — the engine does not enforce it. Your application must check and reject stale resumes.
-- `result.resume` and `result.retry` are convenience functions for in-process use. For cross-process resumption, use `wf.resume(state, input)` instead.

package/skills/moostjs-event-wf/integration.md

@@ -1,180 +0,0 @@
-# Integration — @moostjs/event-wf
-
-> Triggering workflows from HTTP/CLI handlers, using Moost features in steps, and multi-adapter setup.
-
-## Concepts
-
-Workflow steps are regular Moost event handlers. The same interceptor, pipe, and DI mechanisms that work with HTTP and CLI handlers work with workflows. This page covers cross-event-type integration.
-
-## Triggering Workflows from HTTP
-
-```ts
-import { Controller, Param } from 'moost'
-import { Post, Body } from '@moostjs/event-http'
-import { MoostWf } from '@moostjs/event-wf'
-
-interface TTicketContext {
-  ticketId: string
-  description: string
-  status: string
-}
-
-@Controller('tickets')
-export class TicketController {
-  constructor(private wf: MoostWf<TTicketContext>) {}
-
-  @Post()
-  async createTicket(@Body() body: { description: string }) {
-    const result = await this.wf.start('support-ticket', {
-      ticketId: generateId(),
-      description: body.description,
-      status: 'new',
-    })
-    return {
-      ticketId: result.state.context.ticketId,
-      finished: result.finished,
-      inputRequired: result.inputRequired,
-      state: result.finished ? undefined : result.state,
-    }
-  }
-
-  @Post(':id/resume')
-  async resumeTicket(
-    @Param('id') id: string,
-    @Body() body: { state: any, input: any },
-  ) {
-    const result = await this.wf.resume(body.state, body.input)
-    return { ticketId: id, finished: result.finished }
-  }
-}
-```
-
-The workflow state is plain JSON — return it directly to clients or store in a database.
-
-## Triggering Workflows from CLI
-
-```ts
-import { Controller } from 'moost'
-import { Cli, CliOption } from '@moostjs/event-cli'
-import { MoostWf } from '@moostjs/event-wf'
-
-@Controller()
-export class DeployCommand {
-  constructor(private wf: MoostWf) {}
-
-  @Cli('deploy :env')
-  async deploy(
-    @Param('env') env: string,
-    @CliOption('dry-run', 'Simulate without applying') dryRun?: boolean,
-  ) {
-    const result = await this.wf.start('deploy', {
-      environment: env,
-      dryRun: !!dryRun,
-    })
-    return result.finished
-      ? `Deployed to ${env} successfully`
-      : `Deploy paused: ${JSON.stringify(result.inputRequired)}`
-  }
-}
-```
-
-## Multi-Adapter Setup
-
-Register both adapters in a single application:
-
-```ts
-import { Moost } from 'moost'
-import { MoostHttp } from '@moostjs/event-http'
-import { MoostWf } from '@moostjs/event-wf'
-
-const app = new Moost()
-
-app.adapter(new MoostHttp()).listen(3000)
-app.adapter(new MoostWf())
-
-app.registerControllers(
-  TicketController,      // HTTP handlers
-  TicketWfController,    // Workflow steps
-).init()
-```
-
-## Interceptors on Workflow Steps
-
-Use `@Intercept` for pre/post logic on steps:
-
-```ts
-import { Intercept } from 'moost'
-
-@Controller()
-export class TicketWfController {
-  @Step('assign')
-  @Intercept(LogStepExecution)
-  assign(@WorkflowParam('context') ctx: TTicketContext) {
-    ctx.assignee = findAvailableAgent()
-  }
-}
-```
-
-All interceptor priority levels work — guards, error handlers, `AFTER_ALL` cleanup. Global interceptors registered with Moost also apply to workflow steps.
-
-## Pipes for Validation
-
-Use `@Pipe` to transform or validate data flowing into steps:
-
-```ts
-import { Pipe } from 'moost'
-
-@Step('process-data')
-processData(
-  @WorkflowParam('input')
-  @Pipe(validateInput)
-  input: TProcessInput,
-) {
-  // input is validated before reaching this point
-}
-```
-
-## Dependency Injection
-
-Workflow controllers support the same DI as the rest of Moost:
-
-```ts
-@Injectable('FOR_EVENT')
-@Controller()
-export class TicketWfController {
-  constructor(
-    private emailService: EmailService,
-    private ticketRepo: TicketRepository,
-  ) {}
-
-  @Step('notify-assignee')
-  async notifyAssignee(@WorkflowParam('context') ctx: TTicketContext) {
-    await this.emailService.send(ctx.assignee!, `Ticket ${ctx.ticketId} assigned`)
-  }
-
-  @Step('save-ticket')
-  async saveTicket(@WorkflowParam('context') ctx: TTicketContext) {
-    await this.ticketRepo.update(ctx.ticketId, { status: ctx.status })
-  }
-}
-```
-
-## Accessing the Underlying WooksWf
-
-For advanced scenarios:
-
-```ts
-const wf = new MoostWf()
-const wooksWf = wf.getWfApp()
-```
-
-## Best Practices
-
-- Inject `MoostWf` via constructor DI to use it from HTTP/CLI controllers — the adapter instance is registered in the DI container.
-- Keep workflow controllers separate from HTTP/CLI controllers for clarity, even though they can be combined.
-- Global interceptors apply to all event types uniformly — use `contextType` checks if you need event-type-specific behavior.
-
-## Gotchas
-
-- When using `MoostWf` from a constructor-injected service, ensure `app.init()` has been called before starting workflows — steps must be registered first.
-- The adapter name is `'workflow'` (`wf.name === 'workflow'`).

package/skills/moostjs-event-wf/schemas.md

@@ -1,203 +0,0 @@
-# Schemas & Flow Control — @moostjs/event-wf
-
-> Defining step sequences, conditional execution, loops, break/continue, and nested sub-workflows.
-
-## Concepts
-
-A workflow schema is an array attached to a `@Workflow` entry point via `@WorkflowSchema`. It declares which steps run, in what order, and under what conditions. Schemas support linear sequences, conditional steps, loops, break/continue flow control, and nesting.
-
-## Linear Schemas
-
-The simplest schema is a flat list of step IDs:
-
-```ts
-@Workflow('deploy')
-@WorkflowSchema(['build', 'test', 'publish'])
-deploy() {}
-```
-
-Steps run one after another in order.
-
-## Conditional Steps
-
-Add a `condition` to run a step only when it evaluates to `true`:
-
-```ts
-@WorkflowSchema<TCampaignContext>([
-  'prepare-audience',
-  { condition: (ctx) => ctx.audienceSize > 0, id: 'request-approval' },
-  { condition: (ctx) => ctx.approved, id: 'send-emails' },
-  'generate-report',
-])
-```
-
-If a condition returns `false`, that step is skipped and execution continues.
-
-## String Conditions
-
-Conditions can be strings evaluated against the workflow context using a `with(ctx)` scope. This makes them serializable for database storage:
-
-```ts
-@WorkflowSchema<TCampaignContext>([
-  'prepare-audience',
-  { condition: 'audienceSize > 0', id: 'request-approval' },
-  { condition: 'approved', id: 'send-emails' },
-])
-```
-
-String conditions reference context fields directly: `'amount > 100'`, `'status === "active"'`, etc. They are evaluated using `new Function()` with context properties as globals.
-
-## Loops
-
-Use `while` with a nested `steps` array to repeat steps until the condition becomes `false`:
-
-```ts
-@WorkflowSchema<TContext>([
-  {
-    while: (ctx) => !ctx.sent && ctx.retries < 3,
-    steps: ['attempt-send', 'increment-retries'],
-  },
-  { condition: (ctx) => !ctx.sent, id: 'log-failure' },
-])
-```
-
-The `while` condition (function or string) is checked before each iteration.
-
-## Break and Continue
-
-Inside a loop's `steps` array:
-
-```ts
-@WorkflowSchema<TProcessContext>([
-  {
-    while: 'running',
-    steps: [
-      'check-temperature',
-      { break: 'temperature > safeLimit' },   // exits the loop
-      'process-batch',
-      { continue: 'skipCooling' },             // skips to next iteration
-      'cool-down',
-    ],
-  },
-  'shutdown',
-])
-```
-
-- **`break`** — exits the loop immediately when the condition is `true`
-- **`continue`** — skips remaining steps in the current iteration and starts the next one
-
-Both accept function or string conditions.
-
-## Nested Sub-Workflows
-
-Group steps with a `steps` array without `while` to apply a shared condition to a block:
-
-```ts
-@WorkflowSchema<TCampaignContext>([
-  'prepare-audience',
-  {
-    condition: (ctx) => ctx.audienceSize > 1000,
-    steps: ['segment-audience', 'schedule-batches', 'warm-up-ips'],
-  },
-  'send-emails',
-])
-```
-
-## Input in Schema
-
-Pass input to a specific step directly from the schema:
-
-```ts
-@WorkflowSchema([
-  { id: 'notify', input: { channel: 'email' } },
-  { id: 'notify', input: { channel: 'sms' } },
-])
-```
-
-The step receives this via `@WorkflowParam('input')`.
-
-## Schema Type Reference
-
-A schema is an array of items (`TWorkflowSchema<T>`). Each item can be:
-
-| Form | Description |
-|------|-------------|
-| `'stepId'` | Run the step unconditionally |
-| `{ id: 'stepId' }` | Run the step (same as string form) |
-| `{ id: 'stepId', condition: fn \| string }` | Run only if condition passes |
-| `{ id: 'stepId', input: value }` | Run with specific input |
-| `{ steps: [...] }` | Nested group of steps |
-| `{ steps: [...], condition: fn \| string }` | Conditional group |
-| `{ steps: [...], while: fn \| string }` | Loop until condition is false |
-| `{ break: fn \| string }` | Exit enclosing loop if condition passes |
-| `{ continue: fn \| string }` | Skip to next loop iteration if condition passes |
-
-## TypeScript Types
-
-```ts
-type TWorkflowSchema<T> = TWorkflowItem<T>[]
-
-type TWorkflowItem<T> =
-  | string                              // simple step ID
-  | TWorkflowStepSchemaObj<T, any>      // step with condition/input
-  | TSubWorkflowSchemaObj<T>            // nested steps
-  | TWorkflowControl<T>                 // break or continue
-
-interface TWorkflowStepSchemaObj<T, I> {
-  id: string
-  condition?: string | ((ctx: T) => boolean | Promise<boolean>)
-  input?: I
-}
-
-interface TSubWorkflowSchemaObj<T> {
-  steps: TWorkflowSchema<T>
-  condition?: string | ((ctx: T) => boolean | Promise<boolean>)
-  while?: string | ((ctx: T) => boolean | Promise<boolean>)
-}
-
-type TWorkflowControl<T> =
-  | { continue: string | ((ctx: T) => boolean | Promise<boolean>) }
-  | { break: string | ((ctx: T) => boolean | Promise<boolean>) }
-```
-
-## Common Patterns
-
-### Pattern: Retry Loop with Break
-
-```ts
-@WorkflowSchema<TContext>([
-  {
-    while: (ctx) => ctx.attempts < ctx.maxAttempts,
-    steps: [
-      'attempt-operation',
-      { break: 'succeeded' },
-      'wait-before-retry',
-    ],
-  },
-  { condition: (ctx) => ctx.succeeded, id: 'report-success' },
-  { condition: (ctx) => !ctx.succeeded, id: 'escalate-failure' },
-])
-```
-
-### Pattern: Type-Safe Conditions
-
-Pass your context type as a generic to get autocomplete and compile-time checks on conditions:
-
-```ts
-@WorkflowSchema<TOnboardingContext>([
-  'verify-email',
-  { condition: (ctx) => ctx.emailVerified, id: 'collect-profile' },  // ctx is typed
-  { condition: (ctx) => ctx.profileComplete, id: 'send-welcome' },
-])
-```
-
-## Best Practices
-
-- Use function conditions for type safety; use string conditions when schemas are stored in a database.
-- Keep schemas flat when possible — deep nesting reduces readability.
-- The `@Workflow` entry point method body should be empty — all logic lives in the steps.
-
-## Gotchas
-
-- String conditions are evaluated with `new Function()` and `with(ctx)`. Only context properties are available as globals — no access to imports or closures.
-- Condition functions can be async (return `Promise<boolean>`).