v1.0: Queue/Worker rewrite, workflow engine, docs overhaul

.changeset/adapter-drizzle-1.0.md

@@ -0,0 +1,28 @@
+---
+"@vorsteh-queue/adapter-drizzle": major
+---
+
+## @vorsteh-queue/adapter-drizzle 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+Changed: `progress` from nullable to non-nullable INT (default 0)
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`

.changeset/adapter-kysely-1.0.md

@@ -0,0 +1,30 @@
+---
+"@vorsteh-queue/adapter-kysely": major
+---
+
+## @vorsteh-queue/adapter-kysely 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+Changed: `progress` from nullable to non-nullable INT (default 0)
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`
+
+Updated `createQueueJobsTable()` helper and migration files with new schema.

.changeset/adapter-prisma-1.0.md

@@ -0,0 +1,30 @@
+---
+"@vorsteh-queue/adapter-prisma": major
+---
+
+## @vorsteh-queue/adapter-prisma 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+Changed: `progress` from nullable to non-nullable INT (default 0)
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`
+
+Updated `schema.prisma` with new model fields.

.changeset/cli-initial.md

@@ -0,0 +1,14 @@
+---
+"@vorsteh-queue/cli": minor
+---
+
+## @vorsteh-queue/cli — Initial Release
+
+CLI tool for monitoring and managing vorsteh-queue jobs.
+
+- Commands: `status`, `inspect`, `cancel`, `redrive`, `clear`
+- Transports: direct adapter connection or remote GraphQL server
+- `--json` flag on all commands for machine-readable output
+- Configuration via environment variables (`VORSTEH_QUEUE_URL`, `VORSTEH_QUEUE_TOKEN`)
+- `defineCliConfig()` helper for typed configuration
+- Built with citty (unjs CLI framework)

.changeset/core-1.0.md

@@ -0,0 +1,59 @@
+---
+"@vorsteh-queue/core": major
+---
+
+## @vorsteh-queue/core 1.0
+
+### Breaking: Queue/Worker Architecture Split
+
+The `Queue` class is now a producer-only. Job processing is handled by the new `Worker` class.
+
+Before:
+
+```typescript
+const queue = new Queue(adapter, { name: "my-queue" })
+queue.register("job", handler)
+queue.start()
+```
+
+After:
+
+```typescript
+const queue = new Queue(adapter, { name: "my-queue" })
+const worker = new Worker(adapter, { name: "my-queue", concurrency: 5 })
+worker.register("job", handler)
+worker.start()
+
+// Queue is now producer-only — use it to add jobs
+await queue.add("job", { data: "payload" })
+```
+
+### Breaking: Handler Signature
+
+Handlers now receive a `JobContext` with an `AbortSignal` for timeout/cancellation support.
+
+Before: `(job) => Promise<result>`
+After: `(job, { signal, step }) => Promise<result>`
+
+### Breaking: New Statuses
+
+Added `cancelled` and `dead` statuses. `QueueStats` now includes all 7 statuses.
+
+### Breaking: Removed APIs
+
+`queue.register()`, `queue.start()`, `queue.stop()`, `queue.pause()`, `queue.resume()`, `queue.enqueue()`, `queue.dequeue()`
+
+### New Features
+
+- Job cancellation (`queue.cancel()`, `worker.cancelJob()`)
+- Dead-letter queue (`queue.getDeadJobs()`, `queue.redrive()`, `queue.redriveAll()`)
+- Group FIFO ordering (`{ group: "tenant-1" }`)
+- Unique job deduplication (`{ unique: { key: "...", action: "reject" | "replace" } }`)
+- `enqueueAndWait()` — enqueue and wait for result (hybrid event + polling)
+- Typed event emitter on both Queue and Worker
+- Configurable retry strategies (exponential, linear, fixed, custom function)
+- State machine validation for job status transitions
+- Per-handler concurrency limits
+- Job Steps (`step.run()`, `step.sleep()`, `step.all()`) for durable multi-step execution
+- Job Dependencies (`dependsOn`, circular detection)
+- Rate Limiting (token-bucket per handler)

.changeset/node-22-minimum.md

@@ -0,0 +1,13 @@
+---
+"@vorsteh-queue/core": major
+"@vorsteh-queue/adapter-drizzle": major
+"@vorsteh-queue/adapter-prisma": major
+"@vorsteh-queue/adapter-kysely": major
+"@vorsteh-queue/server": major
+"@vorsteh-queue/cli": major
+"create-vorsteh-queue": major
+---
+
+**Breaking:** Minimum Node.js version raised from 20 to 22.
+
+Node.js 22 is the current active LTS. This allows the use of stable native `fetch`, improved `AbortSignal` support, and aligns with the TypeScript 6.x target.

.changeset/retry-runnow-delete.md

@@ -0,0 +1,23 @@
+---
+"@vorsteh-queue/core": minor
+"@vorsteh-queue/adapter-drizzle": minor
+"@vorsteh-queue/adapter-kysely": minor
+"@vorsteh-queue/adapter-prisma": minor
+"@vorsteh-queue/server": minor
+"@vorsteh-queue/cli": minor
+---
+
+## New operations: retry, runNow, deleteJob
+
+Added three new job management operations across the full stack:
+
+- **`retry(jobId)`** — resets a `failed` job to `pending` (clears error, resets attempts to 0)
+- **`runNow(jobId)`** — promotes a `delayed` job to `pending` immediately (sets processAt to now)
+- **`deleteJob(jobId)`** — permanently removes a single job by ID
+
+Available on:
+
+- `Queue` class: `queue.retry()`, `queue.runNow()`, `queue.deleteJob()`
+- `QueueAdapter` interface: `retryJob()`, `runJobNow()`, `deleteJob()`
+- GraphQL API: mutations `retryJob`, `runJobNow`, `deleteJob`
+- CLI: commands `retry`, `run-now`, `delete`

.changeset/server-dashboard-merge.md

@@ -0,0 +1,21 @@
+---
+"@vorsteh-queue/server": minor
+"@vorsteh-queue/core": minor
+---
+
+Integrated web dashboard into the server package and added unified configuration.
+
+**Server (`@vorsteh-queue/server`):**
+
+- Embedded the dashboard UI — served as static assets via Hono when `dashboard: true` (default)
+- Simplified auth: `tokens: string[]`, custom `middleware`, or `false` (removed basic auth)
+- Added `loadConfig()` to load `queue.config.ts` via c12
+- Restructured: `src/api/` (GraphQL schema, auth, pubsub) + `src/ui/` (React SPA)
+- Added `flows` query and implemented the `jobs` query (was a stub)
+- Dashboard communicates with the API via `gql.tada` + `graphql-request`
+- UI: Overview stats, Jobs list (filtered/paginated), Job detail, DLQ, Flows, Flow DAG visualization
+
+**Core (`@vorsteh-queue/core`):**
+
+- Added `getJobs()` and `getFlows()` to `QueueAdapter` interface
+- Implemented in Memory, Drizzle, Kysely, and Prisma adapters

.changeset/server-initial.md

@@ -0,0 +1,17 @@
+---
+"@vorsteh-queue/server": minor
+---
+
+## @vorsteh-queue/server — Initial Release
+
+GraphQL server and monitoring API for vorsteh-queue.
+
+- `createQueueServer(config)` — standalone server (Hono + Node.js)
+- `createQueueMiddleware(config)` — composable Hono middleware
+- GraphQL API (via GraphQL Yoga + Pothos):
+  - Queries: `stats`, `job`, `deadJobs`, `size`
+  - Mutations: `cancelJob`, `redriveJob`, `redriveAll`, `clearJobs`
+  - Subscriptions: `jobStatusChanged`, `statsUpdated` (SSE-based)
+- Authentication: token (Bearer), basic auth, custom middleware, or disabled
+- PubSub for real-time event streaming to GraphQL subscribers
+- `defineConfig()` helper for typed configuration

.changeset/workflow-engine.md

@@ -0,0 +1,66 @@
+---
+"@vorsteh-queue/core": minor
+---
+
+## Workflow Engine Features
+
+### Saga Compensation
+
+Steps can declare `compensate` functions that run in reverse order when a later step fails:
+
+```typescript
+await step.run("charge", () => payments.charge(amount), {
+  compensate: (result) => payments.refund(result.txId),
+})
+```
+
+### Signals / Human-in-the-Loop
+
+Jobs can pause and wait for an external signal:
+
+```typescript
+const approval = await step.waitFor("approval", "manager-decision", {
+  timeout: "24h",
+})
+// External: await queue.signal(jobId, "manager-decision", { approved: true })
+```
+
+### Event Triggers
+
+Automatically create follow-up jobs on completion:
+
+```typescript
+worker.trigger({
+  on: "order",
+  create: "send-receipt",
+  data: (result, job) => ({ email: result.email }),
+  condition: (result) => result.total > 0,
+})
+```
+
+### Flow Producer (Parent-Child Job Trees)
+
+Declarative job trees with parent-child relationships:
+
+```typescript
+const flow = await queue.addFlow({
+  name: "deploy",
+  payload: { version: "1.0" },
+  children: [
+    { name: "build", payload: { target: "linux" } },
+    { name: "test", payload: {}, children: [{ name: "lint", payload: {} }] },
+  ],
+})
+```
+
+- Parent waits in `waiting-children` status until all children complete
+- `failParentOnFailure` cascades child failures upward
+- `ctx.getChildrenResults()` provides children results to parent handlers
+- `queue.getFlowTree(flowId)` returns the full tree for visualization
+
+### New Status: `waiting-children`
+
+Added to the state machine. Valid transitions:
+
+- `pending` → `waiting-children`
+- `waiting-children` → `pending` (all children done), `cancelled`, `failed`

.github/copilot-instructions.md

@@ -1,13 +1,15 @@
 # GitHub Copilot Instructions
 
 ## Development Philosophy
+
 - **Quality over quantity**: Write clean, maintainable, and well-structured code
 - **Senior-level TypeScript**: Leverage advanced TypeScript features for type safety
 - **Minimal and focused**: Every line of code should serve a clear purpose
 - **Performance-conscious**: Consider efficiency and avoid unnecessary complexity
 
-## TypeScript & ESLint Rules
-- **No console.log**: Use proper logging or remove debug statements
+## TypeScript & Linting Rules (oxlint via ultracite)
+
+- **No console.log**: Use proper logging or remove debug statements (`no-console: error`)
 - **Consistent type imports**: Use `import type` for type-only imports
 - **No unused vars**: Prefix with `_` if intentionally unused
 - **No unnecessary conditions**: Avoid redundant null checks
@@ -20,22 +22,46 @@
 - **No useless path segments**: Avoid `/index` in import paths when possible
 - **Prefer directory imports**: Use `../src` instead of `../src/index` for cleaner imports
 
-## Prettier Configuration
-- **Print width**: 100 characters max
+## Formatting Configuration (oxfmt via ultracite)
+
+- **Line width**: 100 characters max
 - **No semicolons**: Use semicolon-free style
-- **Import order**: Follow the specified import grouping:
+- **Trailing commas**: ES5 style
+- **Import sorting**: Handled automatically by oxfmt (`sortImports: true`)
+- **Import order** (enforced by oxfmt):
   1. Types first
   2. React/Next.js/Expo (if applicable)
   3. Third-party modules
   4. @vorsteh-queue packages
   5. Relative imports (~/,../, ./)
 
+## Tooling & Verification
+
+After making code changes, verify with these commands (in this order):
+
+1. `pnpm format:fix` — Apply formatting
+2. `pnpm lint:fix` — Auto-fix lint issues
+3. `pnpm typecheck` — Verify types
+4. `vitest --run` — Run tests (single run, no watch mode)
+
+Always use the pnpm scripts from the root `package.json`. Never call tools directly via `npx` or `pnpm dlx`.
+
+| Tool               | Check            | Fix               |
+| ------------------ | ---------------- | ----------------- |
+| Formatter (oxfmt)  | `pnpm format`    | `pnpm format:fix` |
+| Linter (oxlint)    | `pnpm lint`      | `pnpm lint:fix`   |
+| Types (TypeScript) | `pnpm typecheck` | —                 |
+| Tests (Vitest)     | `vitest --run`   | —                 |
+| Build (Turborepo)  | `pnpm build`     | —                 |
+| Workspace (sherif) | `pnpm lint:ws`   | —                 |
+
 ## Code Generation Guidelines
+
 - Remove all `console.log` statements from generated code
 - Use proper TypeScript types instead of `any` when possible
 - **Use type-fest when available** - Prefer battle-tested utility types from type-fest over custom implementations
-- Add ESLint disable comments only when absolutely necessary
-- Follow the import order specified in prettier config
+- Add lint disable comments only when absolutely necessary
+- Follow the import order enforced by oxfmt
 - Use consistent naming conventions (camelCase for variables, PascalCase for types)
 - **Generic type parameters**: Always prefix with `T` (e.g., `TJobPayload`, `TResult`, `TEventData`)
 - Prefer explicit return types for functions
@@ -46,8 +72,9 @@
 - Optimize for readability and maintainability
 
 ## File Structure
-- Keep imports organized according to prettier rules
+
+- Keep imports organized according to oxfmt rules
 - Use meaningful variable and function names
 - Add proper JSDoc comments for public APIs
 - Prefer composition over inheritance
-- Use readonly arrays and objects where appropriate
+- Use readonly arrays and objects where appropriate