@moostjs/event-wf 0.5.33 → 0.6.1

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/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

@@ -0,0 +1,40 @@
+---
+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

@@ -0,0 +1,138 @@
+# 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

@@ -0,0 +1,179 @@
+# 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.