@gravito/flux 1.0.0-alpha.6 → 1.0.0-beta.2

package/README.zh-TW.md

@@ -1,11 +1,25 @@
 # @gravito/flux
 
-> Gravito 的高效能工作流程引擎，跨平台、型別安全的狀態機。
+> Gravito 的高效能工作流程引擎，跨平台、型別安全的狀態機，強調可追蹤、可重播與可靠重試。
+
+## 核心特色
+
+- **純狀態機模型** - 以明確狀態描述流程，讓每一步清晰可控
+- **鏈式 Builder API** - 型別安全的流程定義方式
+- **儲存介面** - Memory、Bun SQLite，其他儲存可自訂
+- **重試與逾時** - Step 可設定 retries/timeout/when，面對不穩定依賴也能自動恢復
+- **同步/非同步** - 同時支援同步流程與非同步長流程
+- **事件 Hooks** - 監聽流程與步驟生命週期
+- **事件 Hooks** - 監聽流程與步驟生命周期
+- **雙平台支援** - Bun 與 Node.js 均可使用
 
 ## 安裝
 
 ```bash
 bun add @gravito/flux
+
+# npm
+npm install @gravito/flux
 ```
 
 ## 快速開始
@@ -28,3 +42,208 @@ const orderFlow = createWorkflow('order-process')
 const engine = new FluxEngine()
 const result = await engine.execute(orderFlow, { orderId: '123' })
 ```
+
+## 範例
+
+### 訂單履約
+
+```typescript
+const orderWorkflow = createWorkflow('order-fulfillment')
+  .input<{ orderId: string; items: Item[] }>()
+  .step('validate', async (ctx) => {
+    for (const item of ctx.input.items) {
+      const stock = await db.products.getStock(item.productId)
+      if (stock < item.qty) throw new Error(`Out of stock: ${item.productId}`)
+    }
+  })
+  .step(
+    'payment',
+    async (ctx) => {
+      ctx.data.payment = await payment.charge(ctx.input.orderId)
+    },
+    { retries: 3, timeout: 30_000 }
+  )
+  .commit('deduct', async (ctx) => {
+    await inventory.deduct(ctx.data.reservationIds)
+  })
+```
+
+### 影像處理
+
+```typescript
+const uploadWorkflow = createWorkflow('image-processing')
+  .input<{ fileBuffer: Buffer; fileName: string; userId: string }>()
+  .step('validate', async (ctx) => {
+    if (ctx.input.fileBuffer.length > 10 * 1024 * 1024) {
+      throw new Error('File size exceeds 10MB')
+    }
+  })
+  .step('resize', async (ctx) => {
+    ctx.data.thumbnail = await sharp(ctx.input.fileBuffer).resize(200).toBuffer()
+  })
+  .commit('upload', async (ctx) => {
+    ctx.data.url = await s3.upload(ctx.input.fileName, ctx.data.thumbnail)
+  })
+```
+
+### 報表生成
+
+```typescript
+const reportWorkflow = createWorkflow('generate-report')
+  .input<{ reportType: string; dateRange: DateRange; requestedBy: string }>()
+  .step('fetch-data', async (ctx) => {
+    ctx.data.sales = await db.orders.aggregate(ctx.input.dateRange)
+  }, { timeout: 60_000 })
+  .step('calculate', async (ctx) => {
+    ctx.data.metrics = { revenue: 0, orders: 0 }
+  })
+  .commit('upload', async (ctx) => {
+    ctx.data.url = await s3.upload(`reports/${ctx.id}.pdf`, ctx.data.pdf)
+  })
+```
+
+## API
+
+### `createWorkflow(name)`
+
+```typescript
+const flow = createWorkflow('my-workflow')
+  .input<{ value: number }>()
+  .step('step1', handler)
+  .step('step2', handler, { retries: 3 })
+  .commit('save', handler)
+```
+
+### `FluxEngine`
+
+```typescript
+const engine = new FluxEngine({
+  storage: new MemoryStorage(),
+  defaultRetries: 3,
+  defaultTimeout: 30_000,
+  logger: new FluxConsoleLogger(),
+  on: {
+    stepStart: (step, ctx) => {},
+    stepComplete: (step, ctx, result) => {},
+    stepError: (step, ctx, error) => {},
+    workflowComplete: (ctx) => {},
+    workflowError: (ctx, error) => {},
+  },
+})
+```
+
+### Step Options
+
+```typescript
+.step('name', handler, {
+  retries: 5,
+  timeout: 60_000,
+  when: (ctx) => ctx.data.x > 0,
+})
+```
+
+## 分支流程（多支點）
+
+```typescript
+const flow = createWorkflow('event-routing')
+  .input<{ payload: EventPayload }>()
+  .step('classify', async (ctx) => {
+    ctx.data.route = classify(ctx.input.payload)
+  })
+  .step(
+    'auto-handle',
+    async (ctx) => {
+      ctx.data.result = await autoProcess(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'auto' }
+  )
+  .step(
+    'manual-review',
+    async (ctx) => {
+      ctx.data.ticketId = await ticketing.create(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'manual' }
+  )
+  .step(
+    'risk-audit',
+    async (ctx) => {
+      ctx.data.auditId = await auditQueue.enqueue(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'risk' }
+  )
+  .commit('notify', async (ctx) => {
+    await notifier.send(ctx.data)
+  })
+```
+
+## 本地開發視覺化
+
+```typescript
+import { FluxEngine, JsonFileTraceSink } from '@gravito/flux'
+
+const engine = new FluxEngine({
+  trace: new JsonFileTraceSink({ path: './.flux/trace.ndjson', reset: true }),
+})
+```
+
+```bash
+flux dev --trace ./.flux/trace.ndjson --port 4280
+```
+
+### 驗證流程（本 repo）
+
+```bash
+bun run examples/trace-viewer.ts
+bun run dev:viewer
+```
+
+## 企業級追蹤
+
+透過 `FluxTraceSink` 可以把事件流送到你自己的監控、排程或分析模組，建立完整的執行查詢、重播與告警能力。
+
+## 儲存介面
+
+### MemoryStorage
+
+```typescript
+import { FluxEngine, MemoryStorage } from '@gravito/flux'
+const engine = new FluxEngine({ storage: new MemoryStorage() })
+```
+
+### BunSQLiteStorage (Bun only)
+
+```typescript
+import { FluxEngine } from '@gravito/flux'
+import { BunSQLiteStorage } from '@gravito/flux/bun'
+
+const engine = new FluxEngine({
+  storage: new BunSQLiteStorage({ path: './data/workflows.db' })
+})
+```
+
+## Gravito 整合
+
+```typescript
+import { OrbitFlux } from '@gravito/flux'
+
+const core = await PlanetCore.boot({
+  orbits: [
+    new OrbitFlux({
+      storage: 'sqlite',
+      dbPath: './data/workflows.db',
+    })
+  ]
+})
+
+const flux = core.services.get<FluxEngine>('flux')
+await flux.execute(myWorkflow, input)
+```
+
+## 平台支援
+
+| Feature | Bun | Node.js |
+|---------|-----|---------|
+| FluxEngine | ✅ | ✅ |
+| MemoryStorage | ✅ | ✅ |
+| BunSQLiteStorage | ✅ | ❌ |
+| OrbitFlux | ✅ | ✅ |

package/bin/flux.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { dirname, extname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+const help = () => {
+  console.log(`Flux CLI
+
+Usage:
+  flux dev --trace ./.flux/trace.ndjson --port 4280
+`)
+}
+
+if (!command || command === '--help' || command === '-h') {
+  help()
+  process.exit(0)
+}
+
+if (command !== 'dev') {
+  console.error(`Unknown command: ${command}`)
+  help()
+  process.exit(1)
+}
+
+const getArg = (name, fallback) => {
+  const idx = args.indexOf(name)
+  if (idx === -1) return fallback
+  return args[idx + 1] ?? fallback
+}
+
+const port = Number(getArg('--port', '4280'))
+const host = getArg('--host', '127.0.0.1')
+const tracePath = resolve(getArg('--trace', './.flux/trace.ndjson'))
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const viewerRoot = resolve(join(__dirname, '..', 'dev', 'viewer'))
+
+const contentType = (filePath) => {
+  const ext = extname(filePath)
+  switch (ext) {
+    case '.html':
+      return 'text/html; charset=utf-8'
+    case '.js':
+      return 'text/javascript; charset=utf-8'
+    case '.css':
+      return 'text/css; charset=utf-8'
+    case '.json':
+      return 'application/json; charset=utf-8'
+    case '.svg':
+      return 'image/svg+xml'
+    default:
+      return 'text/plain; charset=utf-8'
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url ?? '/', `http://${host}:${port}`)
+    if (url.pathname === '/trace') {
+      try {
+        const data = await readFile(tracePath, 'utf8')
+        res.writeHead(200, {
+          'content-type': 'text/plain; charset=utf-8',
+          'cache-control': 'no-store',
+        })
+        res.end(data)
+      } catch {
+        res.writeHead(204, { 'cache-control': 'no-store' })
+        res.end('')
+      }
+      return
+    }
+
+    const reqPath = url.pathname === '/' ? '/index.html' : url.pathname
+    const filePath = join(viewerRoot, reqPath)
+    const data = await readFile(filePath)
+    res.writeHead(200, {
+      'content-type': contentType(filePath),
+      'cache-control': 'no-store',
+    })
+    res.end(data)
+  } catch (err) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+    res.end('Not Found')
+  }
+})
+
+server.listen(port, host, () => {
+  console.log(`Flux dev viewer running at http://${host}:${port}`)
+  console.log(`Trace file: ${tracePath}`)
+})

package/dev/viewer/app.js

@@ -0,0 +1,131 @@
+const pathEl = document.getElementById('tracePath')
+const updateEl = document.getElementById('lastUpdate')
+const pathElContainer = document.getElementById('path')
+const statusEl = document.getElementById('status')
+const eventsEl = document.getElementById('events')
+
+const state = {
+  events: [],
+  lastHash: '',
+}
+
+const formatTime = (ts) => new Date(ts).toLocaleTimeString()
+
+const parseNdjson = (text) =>
+  text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+
+const hashText = (text) => {
+  let hash = 0
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash << 5) - hash + text.charCodeAt(i)
+    hash |= 0
+  }
+  return String(hash)
+}
+
+const renderPath = (events) => {
+  const steps = []
+  const seen = new Set()
+  for (const event of events) {
+    if (event.stepName && event.type.startsWith('step:')) {
+      if (!seen.has(event.stepName)) {
+        seen.add(event.stepName)
+        steps.push(event.stepName)
+      }
+    }
+  }
+
+  if (!steps.length) {
+    pathElContainer.innerHTML = '<div class="empty">No execution data yet.</div>'
+    return
+  }
+
+  pathElContainer.innerHTML = steps
+    .map((step, index) => {
+      const node = `<span class="node">${step}</span>`
+      const arrow = index < steps.length - 1 ? '<span class="arrow">-&gt;</span>' : ''
+      return `${node}${arrow}`
+    })
+    .join('')
+}
+
+const renderStatus = (events) => {
+  if (!events.length) {
+    statusEl.innerHTML = '<div class="empty">No trace events.</div>'
+    return
+  }
+
+  const lastWorkflow = [...events]
+    .reverse()
+    .find((event) => event.type.startsWith('workflow:'))
+
+  const status = lastWorkflow?.status ?? 'unknown'
+  const badgeClass = status === 'completed' ? 'ok' : status === 'failed' ? 'fail' : ''
+
+  statusEl.innerHTML = `
+    <div>Workflow: <span class="badge ${badgeClass}">${status}</span></div>
+    <div>Workflow ID: ${lastWorkflow?.workflowId ?? '-'}</div>
+    <div>Workflow Name: ${lastWorkflow?.workflowName ?? '-'}</div>
+    <div>Duration: ${lastWorkflow?.duration ? `${lastWorkflow.duration}ms` : '-'}</div>
+  `
+}
+
+const renderEvents = (events) => {
+  if (!events.length) {
+    eventsEl.innerHTML = '<tr><td colspan="6" class="empty">No events yet.</td></tr>'
+    return
+  }
+
+  eventsEl.innerHTML = events
+    .slice()
+    .reverse()
+    .map((event) => {
+      const retry =
+        typeof event.retries === 'number'
+          ? `${event.retries}${event.maxRetries ? `/${event.maxRetries}` : ''}`
+          : '-'
+      const duration = event.duration ? `${event.duration}ms` : '-'
+      const msg = event.error ?? ''
+      return `
+        <tr>
+          <td>${formatTime(event.timestamp)}</td>
+          <td>${event.type}</td>
+          <td>${event.stepName ?? '-'}</td>
+          <td>${retry}</td>
+          <td>${duration}</td>
+          <td>${msg}</td>
+        </tr>
+      `
+    })
+    .join('')
+}
+
+const refresh = async () => {
+  const res = await fetch('/trace', { cache: 'no-store' })
+  const text = await res.text()
+  const hash = hashText(text)
+  if (hash === state.lastHash) return
+
+  state.lastHash = hash
+  state.events = parseNdjson(text)
+  pathEl.textContent = 'Trace: /trace'
+  updateEl.textContent = `Updated: ${new Date().toLocaleTimeString()}`
+
+  renderPath(state.events)
+  renderStatus(state.events)
+  renderEvents(state.events)
+}
+
+refresh()
+setInterval(refresh, 1500)

package/dev/viewer/index.html

@@ -0,0 +1,52 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Flux Dev Viewer</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <header class="topbar">
+      <div>
+        <h1>Flux Dev Viewer</h1>
+        <p class="subtitle">Local workflow trace explorer</p>
+      </div>
+      <div class="meta">
+        <div id="tracePath">Trace: -</div>
+        <div id="lastUpdate">Updated: -</div>
+      </div>
+    </header>
+
+    <main class="grid">
+      <section class="card">
+        <h2>Execution Path</h2>
+        <div id="path" class="path"></div>
+      </section>
+
+      <section class="card">
+        <h2>Status</h2>
+        <div id="status" class="status"></div>
+      </section>
+
+      <section class="card full">
+        <h2>Timeline</h2>
+        <table class="timeline">
+          <thead>
+            <tr>
+              <th>Time</th>
+              <th>Event</th>
+              <th>Step</th>
+              <th>Retry</th>
+              <th>Duration</th>
+              <th>Message</th>
+            </tr>
+          </thead>
+          <tbody id="events"></tbody>
+        </table>
+      </section>
+    </main>
+
+    <script src="/app.js"></script>
+  </body>
+</html>

package/dev/viewer/styles.css

@@ -0,0 +1,163 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  background: #0c0f14;
+  color: #e6eaf2;
+}
+
+.topbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 32px;
+  border-bottom: 1px solid #1d2330;
+  background: linear-gradient(120deg, #111826, #0f1420);
+}
+
+.topbar h1 {
+  margin: 0 0 6px;
+  font-size: 20px;
+  letter-spacing: 0.04em;
+}
+
+.subtitle {
+  margin: 0;
+  color: #93a0b4;
+  font-size: 13px;
+}
+
+.meta {
+  text-align: right;
+  font-size: 12px;
+  color: #9aa6ba;
+  line-height: 1.6;
+}
+
+.grid {
+  display: grid;
+  gap: 18px;
+  padding: 24px 32px 40px;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.card {
+  background: #131a26;
+  border: 1px solid #1d2330;
+  border-radius: 14px;
+  padding: 18px 18px 12px;
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25);
+}
+
+.card.full {
+  grid-column: 1 / -1;
+}
+
+.card h2 {
+  margin: 0 0 14px;
+  font-size: 14px;
+  color: #c7d1e6;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.path {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+}
+
+.node {
+  padding: 8px 12px;
+  border-radius: 999px;
+  background: #1a2333;
+  border: 1px solid #2b3a52;
+  font-size: 12px;
+  color: #d6deec;
+}
+
+.arrow {
+  color: #7c8da7;
+  font-size: 14px;
+}
+
+.status {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+  color: #b9c5d9;
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  background: #1e2532;
+  color: #9db0cc;
+  border: 1px solid #2b364a;
+}
+
+.badge.ok {
+  background: rgba(34, 197, 94, 0.15);
+  color: #7ee4a6;
+  border-color: rgba(34, 197, 94, 0.3);
+}
+
+.badge.fail {
+  background: rgba(248, 113, 113, 0.15);
+  color: #fca5a5;
+  border-color: rgba(248, 113, 113, 0.3);
+}
+
+.timeline {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+
+.timeline th,
+.timeline td {
+  padding: 10px 8px;
+  border-bottom: 1px solid #1d2330;
+  text-align: left;
+}
+
+.timeline th {
+  color: #91a0b7;
+  font-weight: 600;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.timeline tr:last-child td {
+  border-bottom: none;
+}
+
+.empty {
+  color: #7f8ba3;
+  font-size: 12px;
+  padding: 10px 0;
+}
+
+@media (max-width: 900px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+  .meta {
+    text-align: left;
+    margin-top: 10px;
+  }
+  .topbar {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 12px;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/flux",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-beta.2",
   "description": "Platform-agnostic workflow engine for Gravito",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -28,17 +28,24 @@
       }
     }
   },
+  "bin": {
+    "flux": "./bin/flux.js"
+  },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README.zh-TW.md",
+    "bin",
+    "dev"
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "dev:viewer": "node ./bin/flux.js dev --trace ./.flux/trace.ndjson --port 4280",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },
   "peerDependencies": {
-    "gravito-core": "1.0.0-beta.5"
+    "gravito-core": "1.0.0-beta.6"
   },
   "peerDependenciesMeta": {
     "gravito-core": {
@@ -47,7 +54,8 @@
   },
   "devDependencies": {
     "bun-types": "latest",
-    "gravito-core": "1.0.0-beta.5",
+    "gravito-core": "1.0.0-beta.6",
+    "tsup": "^8.5.1",
     "typescript": "^5.0.0"
   },
   "keywords": [

package/dist/node/index.cjs

@@ -1,651 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-
-// src/index.node.ts
-var exports_index_node = {};
-__export(exports_index_node, {
-  createWorkflow: () => createWorkflow,
-  WorkflowBuilder: () => WorkflowBuilder,
-  StepExecutor: () => StepExecutor,
-  StateMachine: () => StateMachine,
-  OrbitFlux: () => OrbitFlux,
-  MemoryStorage: () => MemoryStorage,
-  FluxSilentLogger: () => FluxSilentLogger,
-  FluxEngine: () => FluxEngine,
-  FluxConsoleLogger: () => FluxConsoleLogger,
-  ContextManager: () => ContextManager
-});
-module.exports = __toCommonJS(exports_index_node);
-
-// src/builder/WorkflowBuilder.ts
-class WorkflowBuilder {
-  _name;
-  _steps = [];
-  _validateInput;
-  constructor(name) {
-    this._name = name;
-  }
-  input() {
-    return this;
-  }
-  validate(validator) {
-    this._validateInput = validator;
-    return this;
-  }
-  step(name, handler, options) {
-    this._steps.push({
-      name,
-      handler,
-      retries: options?.retries,
-      timeout: options?.timeout,
-      when: options?.when,
-      commit: false
-    });
-    return this;
-  }
-  commit(name, handler, options) {
-    this._steps.push({
-      name,
-      handler,
-      retries: options?.retries,
-      timeout: options?.timeout,
-      when: options?.when,
-      commit: true
-    });
-    return this;
-  }
-  build() {
-    if (this._steps.length === 0) {
-      throw new Error(`Workflow "${this._name}" has no steps`);
-    }
-    return {
-      name: this._name,
-      steps: [...this._steps],
-      validateInput: this._validateInput
-    };
-  }
-  get name() {
-    return this._name;
-  }
-  get stepCount() {
-    return this._steps.length;
-  }
-}
-function createWorkflow(name) {
-  return new WorkflowBuilder(name);
-}
-// src/core/ContextManager.ts
-function generateId() {
-  return crypto.randomUUID();
-}
-
-class ContextManager {
-  create(name, input, stepCount) {
-    const history = Array.from({ length: stepCount }, (_, _i) => ({
-      name: "",
-      status: "pending",
-      retries: 0
-    }));
-    return {
-      id: generateId(),
-      name,
-      input,
-      data: {},
-      status: "pending",
-      currentStep: 0,
-      history
-    };
-  }
-  restore(state) {
-    return {
-      id: state.id,
-      name: state.name,
-      input: state.input,
-      data: { ...state.data },
-      status: state.status,
-      currentStep: state.currentStep,
-      history: state.history.map((h) => ({ ...h }))
-    };
-  }
-  toState(ctx) {
-    return {
-      id: ctx.id,
-      name: ctx.name,
-      status: ctx.status,
-      input: ctx.input,
-      data: { ...ctx.data },
-      currentStep: ctx.currentStep,
-      history: ctx.history.map((h) => ({ ...h })),
-      createdAt: new Date,
-      updatedAt: new Date
-    };
-  }
-  updateStatus(ctx, status) {
-    return {
-      ...ctx,
-      status
-    };
-  }
-  advanceStep(ctx) {
-    return {
-      ...ctx,
-      currentStep: ctx.currentStep + 1
-    };
-  }
-  setStepName(ctx, index, name) {
-    if (ctx.history[index]) {
-      ctx.history[index].name = name;
-    }
-  }
-}
-
-// src/core/StateMachine.ts
-var TRANSITIONS = {
-  pending: ["running", "failed"],
-  running: ["paused", "completed", "failed"],
-  paused: ["running", "failed"],
-  completed: [],
-  failed: ["pending"]
-};
-
-class StateMachine extends EventTarget {
-  _status = "pending";
-  get status() {
-    return this._status;
-  }
-  canTransition(to) {
-    return TRANSITIONS[this._status].includes(to);
-  }
-  transition(to) {
-    if (!this.canTransition(to)) {
-      throw new Error(`Invalid state transition: ${this._status} → ${to}`);
-    }
-    const from = this._status;
-    this._status = to;
-    this.dispatchEvent(new CustomEvent("transition", {
-      detail: { from, to }
-    }));
-  }
-  forceStatus(status) {
-    this._status = status;
-  }
-  isTerminal() {
-    return this._status === "completed" || this._status === "failed";
-  }
-  canExecute() {
-    return this._status === "pending" || this._status === "paused";
-  }
-}
-
-// src/core/StepExecutor.ts
-class StepExecutor {
-  defaultRetries;
-  defaultTimeout;
-  constructor(options = {}) {
-    this.defaultRetries = options.defaultRetries ?? 3;
-    this.defaultTimeout = options.defaultTimeout ?? 30000;
-  }
-  async execute(step, ctx, execution) {
-    const maxRetries = step.retries ?? this.defaultRetries;
-    const timeout = step.timeout ?? this.defaultTimeout;
-    const startTime = Date.now();
-    if (step.when && !step.when(ctx)) {
-      execution.status = "skipped";
-      return {
-        success: true,
-        duration: 0
-      };
-    }
-    execution.status = "running";
-    execution.startedAt = new Date;
-    let lastError;
-    for (let attempt = 0;attempt <= maxRetries; attempt++) {
-      execution.retries = attempt;
-      try {
-        await this.executeWithTimeout(step.handler, ctx, timeout);
-        execution.status = "completed";
-        execution.completedAt = new Date;
-        execution.duration = Date.now() - startTime;
-        return {
-          success: true,
-          duration: execution.duration
-        };
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        if (attempt < maxRetries) {
-          await this.sleep(Math.min(1000 * 2 ** attempt, 1e4));
-        }
-      }
-    }
-    execution.status = "failed";
-    execution.completedAt = new Date;
-    execution.duration = Date.now() - startTime;
-    execution.error = lastError?.message;
-    return {
-      success: false,
-      error: lastError,
-      duration: execution.duration
-    };
-  }
-  async executeWithTimeout(handler, ctx, timeout) {
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error("Step timeout")), timeout);
-    });
-    await Promise.race([Promise.resolve(handler(ctx)), timeoutPromise]);
-  }
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-}
-
-// src/storage/MemoryStorage.ts
-class MemoryStorage {
-  store = new Map;
-  async save(state) {
-    this.store.set(state.id, {
-      ...state,
-      updatedAt: new Date
-    });
-  }
-  async load(id) {
-    return this.store.get(id) ?? null;
-  }
-  async list(filter) {
-    let results = Array.from(this.store.values());
-    if (filter?.name) {
-      results = results.filter((s) => s.name === filter.name);
-    }
-    if (filter?.status) {
-      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
-      results = results.filter((s) => statuses.includes(s.status));
-    }
-    results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-    if (filter?.offset) {
-      results = results.slice(filter.offset);
-    }
-    if (filter?.limit) {
-      results = results.slice(0, filter.limit);
-    }
-    return results;
-  }
-  async delete(id) {
-    this.store.delete(id);
-  }
-  async init() {}
-  async close() {
-    this.store.clear();
-  }
-  size() {
-    return this.store.size;
-  }
-}
-
-// src/engine/FluxEngine.ts
-class FluxEngine {
-  storage;
-  executor;
-  contextManager;
-  config;
-  constructor(config = {}) {
-    this.config = config;
-    this.storage = config.storage ?? new MemoryStorage;
-    this.executor = new StepExecutor({
-      defaultRetries: config.defaultRetries,
-      defaultTimeout: config.defaultTimeout
-    });
-    this.contextManager = new ContextManager;
-  }
-  async execute(workflow, input) {
-    const startTime = Date.now();
-    const definition = workflow instanceof WorkflowBuilder ? workflow.build() : workflow;
-    if (definition.validateInput && !definition.validateInput(input)) {
-      throw new Error(`Invalid input for workflow "${definition.name}"`);
-    }
-    const ctx = this.contextManager.create(definition.name, input, definition.steps.length);
-    const stateMachine = new StateMachine;
-    await this.storage.save(this.contextManager.toState(ctx));
-    try {
-      stateMachine.transition("running");
-      Object.assign(ctx, { status: "running" });
-      for (let i = 0;i < definition.steps.length; i++) {
-        const step = definition.steps[i];
-        const execution = ctx.history[i];
-        this.contextManager.setStepName(ctx, i, step.name);
-        Object.assign(ctx, { currentStep: i });
-        this.config.on?.stepStart?.(step.name, ctx);
-        const result = await this.executor.execute(step, ctx, execution);
-        if (result.success) {
-          this.config.on?.stepComplete?.(step.name, ctx, result);
-        } else {
-          this.config.on?.stepError?.(step.name, ctx, result.error);
-          stateMachine.transition("failed");
-          Object.assign(ctx, { status: "failed" });
-          await this.storage.save({
-            ...this.contextManager.toState(ctx),
-            error: result.error?.message
-          });
-          return {
-            id: ctx.id,
-            status: "failed",
-            data: ctx.data,
-            history: ctx.history,
-            duration: Date.now() - startTime,
-            error: result.error
-          };
-        }
-        await this.storage.save(this.contextManager.toState(ctx));
-      }
-      stateMachine.transition("completed");
-      Object.assign(ctx, { status: "completed" });
-      await this.storage.save({
-        ...this.contextManager.toState(ctx),
-        completedAt: new Date
-      });
-      this.config.on?.workflowComplete?.(ctx);
-      return {
-        id: ctx.id,
-        status: "completed",
-        data: ctx.data,
-        history: ctx.history,
-        duration: Date.now() - startTime
-      };
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      this.config.on?.workflowError?.(ctx, err);
-      stateMachine.forceStatus("failed");
-      Object.assign(ctx, { status: "failed" });
-      await this.storage.save({
-        ...this.contextManager.toState(ctx),
-        error: err.message
-      });
-      return {
-        id: ctx.id,
-        status: "failed",
-        data: ctx.data,
-        history: ctx.history,
-        duration: Date.now() - startTime,
-        error: err
-      };
-    }
-  }
-  async resume(workflowId) {
-    const state = await this.storage.load(workflowId);
-    if (!state) {
-      return null;
-    }
-    throw new Error("Resume not yet implemented");
-  }
-  async get(workflowId) {
-    return this.storage.load(workflowId);
-  }
-  async list(filter) {
-    return this.storage.list(filter);
-  }
-  async init() {
-    await this.storage.init?.();
-  }
-  async close() {
-    await this.storage.close?.();
-  }
-}
-// src/logger/FluxLogger.ts
-class FluxConsoleLogger {
-  prefix;
-  constructor(prefix = "[Flux]") {
-    this.prefix = prefix;
-  }
-  debug(message, ...args) {
-    console.debug(`${this.prefix} ${message}`, ...args);
-  }
-  info(message, ...args) {
-    console.info(`${this.prefix} ${message}`, ...args);
-  }
-  warn(message, ...args) {
-    console.warn(`${this.prefix} ${message}`, ...args);
-  }
-  error(message, ...args) {
-    console.error(`${this.prefix} ${message}`, ...args);
-  }
-}
-
-class FluxSilentLogger {
-  debug() {}
-  info() {}
-  warn() {}
-  error() {}
-}
-// src/storage/BunSQLiteStorage.ts
-var import_bun_sqlite = require("bun:sqlite");
-
-class BunSQLiteStorage {
-  db;
-  tableName;
-  initialized = false;
-  constructor(options = {}) {
-    this.db = new import_bun_sqlite.Database(options.path ?? ":memory:");
-    this.tableName = options.tableName ?? "flux_workflows";
-  }
-  async init() {
-    if (this.initialized) {
-      return;
-    }
-    this.db.run(`
-      CREATE TABLE IF NOT EXISTS ${this.tableName} (
-        id TEXT PRIMARY KEY,
-        name TEXT NOT NULL,
-        status TEXT NOT NULL,
-        input TEXT NOT NULL,
-        data TEXT NOT NULL,
-        current_step INTEGER NOT NULL,
-        history TEXT NOT NULL,
-        error TEXT,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL,
-        completed_at TEXT
-      )
-    `);
-    this.db.run(`
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_name 
-      ON ${this.tableName}(name)
-    `);
-    this.db.run(`
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_status 
-      ON ${this.tableName}(status)
-    `);
-    this.db.run(`
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created 
-      ON ${this.tableName}(created_at DESC)
-    `);
-    this.initialized = true;
-  }
-  async save(state) {
-    await this.init();
-    const stmt = this.db.prepare(`
-      INSERT OR REPLACE INTO ${this.tableName} 
-      (id, name, status, input, data, current_step, history, error, created_at, updated_at, completed_at)
-      VALUES ($id, $name, $status, $input, $data, $currentStep, $history, $error, $createdAt, $updatedAt, $completedAt)
-    `);
-    stmt.run({
-      $id: state.id,
-      $name: state.name,
-      $status: state.status,
-      $input: JSON.stringify(state.input),
-      $data: JSON.stringify(state.data),
-      $currentStep: state.currentStep,
-      $history: JSON.stringify(state.history),
-      $error: state.error ?? null,
-      $createdAt: state.createdAt.toISOString(),
-      $updatedAt: state.updatedAt.toISOString(),
-      $completedAt: state.completedAt?.toISOString() ?? null
-    });
-  }
-  async load(id) {
-    await this.init();
-    const stmt = this.db.prepare(`
-      SELECT * FROM ${this.tableName} WHERE id = $id
-    `);
-    const row = stmt.get({ $id: id });
-    if (!row) {
-      return null;
-    }
-    return this.rowToState(row);
-  }
-  async list(filter) {
-    await this.init();
-    let query = `SELECT * FROM ${this.tableName} WHERE 1=1`;
-    const params = {};
-    if (filter?.name) {
-      query += " AND name = $name";
-      params.$name = filter.name;
-    }
-    if (filter?.status) {
-      if (Array.isArray(filter.status)) {
-        const placeholders = filter.status.map((_, i) => `$status${i}`).join(", ");
-        query += ` AND status IN (${placeholders})`;
-        filter.status.forEach((s, i) => {
-          params[`$status${i}`] = s;
-        });
-      } else {
-        query += " AND status = $status";
-        params.$status = filter.status;
-      }
-    }
-    query += " ORDER BY created_at DESC";
-    if (filter?.limit) {
-      query += " LIMIT $limit";
-      params.$limit = filter.limit;
-    }
-    if (filter?.offset) {
-      query += " OFFSET $offset";
-      params.$offset = filter.offset;
-    }
-    const stmt = this.db.prepare(query);
-    const rows = stmt.all(params);
-    return rows.map((row) => this.rowToState(row));
-  }
-  async delete(id) {
-    await this.init();
-    const stmt = this.db.prepare(`
-      DELETE FROM ${this.tableName} WHERE id = $id
-    `);
-    stmt.run({ $id: id });
-  }
-  async close() {
-    this.db.close();
-    this.initialized = false;
-  }
-  rowToState(row) {
-    return {
-      id: row.id,
-      name: row.name,
-      status: row.status,
-      input: JSON.parse(row.input),
-      data: JSON.parse(row.data),
-      currentStep: row.current_step,
-      history: JSON.parse(row.history),
-      error: row.error ?? undefined,
-      createdAt: new Date(row.created_at),
-      updatedAt: new Date(row.updated_at),
-      completedAt: row.completed_at ? new Date(row.completed_at) : undefined
-    };
-  }
-  getDatabase() {
-    return this.db;
-  }
-  vacuum() {
-    this.db.run("VACUUM");
-  }
-}
-
-// src/orbit/OrbitFlux.ts
-class OrbitFlux {
-  options;
-  engine;
-  constructor(options = {}) {
-    this.options = {
-      storage: "memory",
-      exposeAs: "flux",
-      defaultRetries: 3,
-      defaultTimeout: 30000,
-      ...options
-    };
-  }
-  static configure(options = {}) {
-    return new OrbitFlux(options);
-  }
-  async install(core) {
-    const { storage, dbPath, exposeAs, defaultRetries, defaultTimeout, logger } = this.options;
-    let storageAdapter;
-    if (typeof storage === "string") {
-      switch (storage) {
-        case "sqlite":
-          storageAdapter = new BunSQLiteStorage({ path: dbPath });
-          break;
-        default:
-          storageAdapter = new MemoryStorage;
-      }
-    } else {
-      storageAdapter = storage;
-    }
-    await storageAdapter.init?.();
-    const engineConfig = {
-      storage: storageAdapter,
-      defaultRetries,
-      defaultTimeout,
-      logger: logger ?? {
-        debug: (msg) => core.logger.debug(`[Flux] ${msg}`),
-        info: (msg) => core.logger.info(`[Flux] ${msg}`),
-        warn: (msg) => core.logger.warn(`[Flux] ${msg}`),
-        error: (msg) => core.logger.error(`[Flux] ${msg}`)
-      },
-      on: {
-        stepStart: (step) => {
-          core.hooks.doAction("flux:step:start", { step });
-        },
-        stepComplete: (step, ctx, result) => {
-          core.hooks.doAction("flux:step:complete", { step, ctx, result });
-        },
-        stepError: (step, ctx, error) => {
-          core.hooks.doAction("flux:step:error", { step, ctx, error });
-        },
-        workflowComplete: (ctx) => {
-          core.hooks.doAction("flux:workflow:complete", { ctx });
-        },
-        workflowError: (ctx, error) => {
-          core.hooks.doAction("flux:workflow:error", { ctx, error });
-        }
-      }
-    };
-    this.engine = new FluxEngine(engineConfig);
-    core.services.set(exposeAs, this.engine);
-    core.logger.info(`[OrbitFlux] Initialized (Storage: ${typeof storage === "string" ? storage : "custom"})`);
-  }
-  getEngine() {
-    return this.engine;
-  }
-}