@ngxtm/devkit 3.15.0 → 3.17.0

package/skills/dbos-python/references/workflow-control.md

@@ -0,0 +1,77 @@
+---
+title: Cancel, Resume, and Fork Workflows
+impact: MEDIUM
+impactDescription: Control running workflows and recover from failures
+tags: workflow, cancel, resume, fork, control
+---
+
+## Cancel, Resume, and Fork Workflows
+
+Use these methods to control workflow execution: stop runaway workflows, retry failed ones, or restart from a specific step.
+
+**Incorrect (expecting immediate cancellation):**
+
+```python
+DBOS.cancel_workflow(workflow_id)
+# Wrong: assuming the workflow stopped immediately
+cleanup_resources()  # May race with workflow still running its current step
+```
+
+**Correct (wait for cancellation to complete):**
+
+```python
+DBOS.cancel_workflow(workflow_id)
+# Cancellation happens at the START of the next step
+# Wait for workflow to actually stop
+handle = DBOS.retrieve_workflow(workflow_id)
+status = handle.get_status()
+while status.status == "PENDING":
+    time.sleep(0.5)
+    status = handle.get_status()
+# Now safe to clean up
+cleanup_resources()
+```
+
+### Cancel
+
+Stop a workflow and remove it from its queue:
+
+```python
+DBOS.cancel_workflow(workflow_id)  # Cancels workflow and all children
+```
+
+### Resume
+
+Restart a stopped workflow from its last completed step:
+
+```python
+# Resume a cancelled or failed workflow
+handle = DBOS.resume_workflow(workflow_id)
+result = handle.get_result()
+
+# Can also bypass queue for an enqueued workflow
+handle = DBOS.resume_workflow(enqueued_workflow_id)
+```
+
+### Fork
+
+Start a new workflow from a specific step of an existing one:
+
+```python
+# Get steps to find the right starting point
+steps = DBOS.list_workflow_steps(workflow_id)
+for step in steps:
+    print(f"Step {step['function_id']}: {step['function_name']}")
+
+# Fork from step 3 (skips steps 1-2, uses their saved results)
+new_handle = DBOS.fork_workflow(workflow_id, start_step=3)
+
+# Fork to run on a new application version (useful for patching bugs)
+new_handle = DBOS.fork_workflow(
+    workflow_id,
+    start_step=3,
+    application_version="2.0.0"
+)
+```
+
+Reference: [Workflow Management](https://docs.dbos.dev/python/tutorials/workflow-management)

package/skills/dbos-python/references/workflow-determinism.md

@@ -0,0 +1,53 @@
+---
+title: Keep Workflows Deterministic
+impact: CRITICAL
+impactDescription: Non-deterministic workflows cannot recover correctly
+tags: workflow, determinism, recovery, reliability
+---
+
+## Keep Workflows Deterministic
+
+Workflow functions must be deterministic: given the same inputs and step return values, they must invoke the same steps in the same order. Non-deterministic operations must be moved to steps.
+
+**Incorrect (non-deterministic workflow):**
+
+```python
+import random
+
+@DBOS.workflow()
+def example_workflow():
+    # Random number in workflow breaks recovery!
+    choice = random.randint(0, 1)
+    if choice == 0:
+        step_one()
+    else:
+        step_two()
+```
+
+**Correct (non-determinism in step):**
+
+```python
+import random
+
+@DBOS.step()
+def generate_choice():
+    return random.randint(0, 1)
+
+@DBOS.workflow()
+def example_workflow():
+    # Random number generated in step - result is saved
+    choice = generate_choice()
+    if choice == 0:
+        step_one()
+    else:
+        step_two()
+```
+
+Non-deterministic operations that must be in steps:
+- Random number generation
+- Getting current time
+- Accessing external APIs
+- Reading files
+- Database queries (use transactions or steps)
+
+Reference: [Workflow Determinism](https://docs.dbos.dev/python/tutorials/workflow-tutorial#determinism)

package/skills/dbos-python/references/workflow-introspection.md

@@ -0,0 +1,68 @@
+---
+title: List and Inspect Workflows
+impact: MEDIUM
+impactDescription: Enables monitoring and management of workflow state
+tags: workflow, list, introspection, status, monitoring
+---
+
+## List and Inspect Workflows
+
+Use `DBOS.list_workflows()` to query workflows by status, name, queue, or other criteria.
+
+**Incorrect (loading unnecessary data):**
+
+```python
+# Loading inputs/outputs when not needed is slow
+workflows = DBOS.list_workflows(status="PENDING")
+for w in workflows:
+    print(w.workflow_id)  # Only using ID
+```
+
+**Correct (optimize with load flags):**
+
+```python
+# Disable loading inputs/outputs for better performance
+workflows = DBOS.list_workflows(
+    status="PENDING",
+    load_input=False,
+    load_output=False
+)
+for w in workflows:
+    print(f"{w.workflow_id}: {w.status}")
+```
+
+Common queries:
+
+```python
+# Find failed workflows
+failed = DBOS.list_workflows(status="ERROR", limit=100)
+
+# Find workflows by name
+processing = DBOS.list_workflows(
+    name="process_task",
+    status=["PENDING", "ENQUEUED"]
+)
+
+# Find workflows on a specific queue
+queued = DBOS.list_workflows(queue_name="high_priority")
+
+# Only queued workflows (shortcut)
+queued = DBOS.list_queued_workflows(queue_name="task_queue")
+
+# Find old version workflows for blue-green deploys
+old = DBOS.list_workflows(
+    app_version="1.0.0",
+    status=["PENDING", "ENQUEUED"]
+)
+
+# Get workflow steps
+steps = DBOS.list_workflow_steps(workflow_id)
+for step in steps:
+    print(f"Step {step['function_id']}: {step['function_name']}")
+```
+
+WorkflowStatus fields: `workflow_id`, `status`, `name`, `queue_name`, `created_at`, `input`, `output`, `error`
+
+Status values: `ENQUEUED`, `PENDING`, `SUCCESS`, `ERROR`, `CANCELLED`, `MAX_RECOVERY_ATTEMPTS_EXCEEDED`
+
+Reference: [Workflow Management](https://docs.dbos.dev/python/tutorials/workflow-management)

package/skills/dbos-python/references/workflow-timeout.md

@@ -0,0 +1,59 @@
+---
+title: Set Workflow Timeouts
+impact: CRITICAL
+impactDescription: Prevents runaway workflows from consuming resources
+tags: timeout, cancel, deadline, limits
+---
+
+## Set Workflow Timeouts
+
+Use `SetWorkflowTimeout` to limit workflow execution time. Timed-out workflows are cancelled.
+
+**Incorrect (no timeout):**
+
+```python
+@DBOS.workflow()
+def potentially_long_workflow():
+    # Could run forever!
+    while not done:
+        process_next()
+```
+
+**Correct (with timeout):**
+
+```python
+from dbos import SetWorkflowTimeout
+
+@DBOS.workflow()
+def bounded_workflow():
+    while not done:
+        process_next()
+
+# Workflow must complete within 60 seconds
+with SetWorkflowTimeout(60):
+    bounded_workflow()
+
+# Or with start_workflow
+with SetWorkflowTimeout(60):
+    handle = DBOS.start_workflow(bounded_workflow)
+```
+
+Timeout behavior:
+- Timeout is **start-to-completion** (doesn't count queue wait time)
+- Timeouts are **durable** (persist across restarts)
+- Cancellation happens at the **beginning of the next step**
+- **All child workflows** are also cancelled
+
+With queues:
+
+```python
+queue = Queue("example_queue")
+
+# Timeout starts when dequeued, not when enqueued
+with SetWorkflowTimeout(30):
+    queue.enqueue(my_workflow)
+```
+
+Timeouts work with long durations (hours, days, weeks) since they're stored in the database.
+
+Reference: [Workflow Timeouts](https://docs.dbos.dev/python/tutorials/workflow-tutorial#workflow-timeouts)

package/skills/dbos-typescript/AGENTS.md

@@ -0,0 +1,94 @@
+# dbos-typescript
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, using DBOSClient from external applications, or building applications that need to be resilient to failures.
+
+## Structure
+
+```
+dbos-typescript/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Lifecycle | CRITICAL | `lifecycle-` |
+| 2 | Workflow | CRITICAL | `workflow-` |
+| 3 | Step | HIGH | `step-` |
+| 4 | Queue | HIGH | `queue-` |
+| 5 | Communication | MEDIUM | `comm-` |
+| 6 | Pattern | MEDIUM | `pattern-` |
+| 7 | Testing | LOW-MEDIUM | `test-` |
+| 8 | Client | MEDIUM | `client-` |
+| 9 | Advanced | LOW | `advanced-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
+
+## Available References
+
+**Advanced** (`advanced-`):
+- `references/advanced-patching.md`
+- `references/advanced-versioning.md`
+
+**Client** (`client-`):
+- `references/client-enqueue.md`
+- `references/client-setup.md`
+
+**Communication** (`comm-`):
+- `references/comm-events.md`
+- `references/comm-messages.md`
+- `references/comm-streaming.md`
+
+**Lifecycle** (`lifecycle-`):
+- `references/lifecycle-config.md`
+- `references/lifecycle-express.md`
+
+**Pattern** (`pattern-`):
+- `references/pattern-classes.md`
+- `references/pattern-debouncing.md`
+- `references/pattern-idempotency.md`
+- `references/pattern-scheduled.md`
+- `references/pattern-sleep.md`
+
+**Queue** (`queue-`):
+- `references/queue-basics.md`
+- `references/queue-concurrency.md`
+- `references/queue-deduplication.md`
+- `references/queue-listening.md`
+- `references/queue-partitioning.md`
+- `references/queue-priority.md`
+- `references/queue-rate-limiting.md`
+
+**Step** (`step-`):
+- `references/step-basics.md`
+- `references/step-retries.md`
+- `references/step-transactions.md`
+
+**Testing** (`test-`):
+- `references/test-setup.md`
+
+**Workflow** (`workflow-`):
+- `references/workflow-background.md`
+- `references/workflow-constraints.md`
+- `references/workflow-control.md`
+- `references/workflow-determinism.md`
+- `references/workflow-introspection.md`
+- `references/workflow-timeout.md`
+
+---
+
+*31 reference files across 9 categories*

package/skills/dbos-typescript/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

package/skills/dbos-typescript/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: dbos-typescript
+description: "DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, usi..."
+risk: safe
+source: https://docs.dbos.dev/
+license: MIT
+metadata:
+  author: dbos
+  version: "1.0.0"
+  organization: DBOS
+  date: January 2026
+  abstract: Comprehensive guide for building fault-tolerant TypeScript applications with DBOS. Covers workflows, steps, queues, communication patterns, and best practices for durable execution.
+---
+
+# DBOS TypeScript Best Practices
+
+Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows.
+
+## When to Use
+
+Reference these guidelines when:
+- Adding DBOS to existing TypeScript code
+- Creating workflows and steps
+- Using queues for concurrency control
+- Implementing workflow communication (events, messages, streams)
+- Configuring and launching DBOS applications
+- Using DBOSClient from external applications
+- Testing DBOS applications
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Lifecycle | CRITICAL | `lifecycle-` |
+| 2 | Workflow | CRITICAL | `workflow-` |
+| 3 | Step | HIGH | `step-` |
+| 4 | Queue | HIGH | `queue-` |
+| 5 | Communication | MEDIUM | `comm-` |
+| 6 | Pattern | MEDIUM | `pattern-` |
+| 7 | Testing | LOW-MEDIUM | `test-` |
+| 8 | Client | MEDIUM | `client-` |
+| 9 | Advanced | LOW | `advanced-` |
+
+## Critical Rules
+
+### Installation
+
+Always install the latest version of DBOS:
+
+```bash
+npm install @dbos-inc/dbos-sdk@latest
+```
+
+### DBOS Configuration and Launch
+
+A DBOS application MUST configure and launch DBOS before running any workflows:
+
+```typescript
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+async function main() {
+  DBOS.setConfig({
+    name: "my-app",
+    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  });
+  await DBOS.launch();
+  await myWorkflow();
+}
+
+main().catch(console.log);
+```
+
+### Workflow and Step Structure
+
+Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using `DBOS.runStep`:
+
+```typescript
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+async function fetchData() {
+  return await fetch("https://api.example.com").then(r => r.json());
+}
+
+async function myWorkflowFn() {
+  const result = await DBOS.runStep(fetchData, { name: "fetchData" });
+  return result;
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+### Key Constraints
+
+- Do NOT call, start, or enqueue workflows from within steps
+- Do NOT use threads or uncontrolled concurrency to start workflows - use `DBOS.startWorkflow` or queues
+- Workflows MUST be deterministic - non-deterministic operations go in steps
+- Do NOT modify global variables from workflows or steps
+
+## How to Use
+
+Read individual rule files for detailed explanations and examples:
+
+```
+references/lifecycle-config.md
+references/workflow-determinism.md
+references/queue-concurrency.md
+```
+
+## References
+
+- https://docs.dbos.dev/
+- https://github.com/dbos-inc/dbos-transact-ts

package/skills/dbos-typescript/references/_sections.md

@@ -0,0 +1,41 @@
+# Section Definitions
+
+This file defines the rule categories for DBOS TypeScript best practices. Rules are automatically assigned to sections based on their filename prefix.
+
+---
+
+## 1. Lifecycle (lifecycle)
+**Impact:** CRITICAL
+**Description:** DBOS configuration, initialization, and launch patterns. Foundation for all DBOS applications.
+
+## 2. Workflow (workflow)
+**Impact:** CRITICAL
+**Description:** Workflow creation, determinism requirements, background execution, and workflow IDs.
+
+## 3. Step (step)
+**Impact:** HIGH
+**Description:** Step creation, retries, transactions via datasources, and when to use steps vs workflows.
+
+## 4. Queue (queue)
+**Impact:** HIGH
+**Description:** WorkflowQueue creation, concurrency limits, rate limiting, partitioning, and priority.
+
+## 5. Communication (comm)
+**Impact:** MEDIUM
+**Description:** Workflow events, messages, and streaming for inter-workflow communication.
+
+## 6. Pattern (pattern)
+**Impact:** MEDIUM
+**Description:** Common patterns including idempotency, scheduled workflows, debouncing, and class instances.
+
+## 7. Testing (test)
+**Impact:** LOW-MEDIUM
+**Description:** Testing DBOS applications with Jest, mocking, and integration test setup.
+
+## 8. Client (client)
+**Impact:** MEDIUM
+**Description:** DBOSClient for interacting with DBOS from external applications.
+
+## 9. Advanced (advanced)
+**Impact:** LOW
+**Description:** Workflow versioning, patching, and safe code upgrades.

package/skills/dbos-typescript/references/advanced-patching.md

@@ -0,0 +1,72 @@
+---
+title: Use Patching for Safe Workflow Upgrades
+impact: LOW
+impactDescription: Safely deploy breaking workflow changes without disrupting in-progress workflows
+tags: advanced, patching, upgrade, breaking-change
+---
+
+## Use Patching for Safe Workflow Upgrades
+
+Use `DBOS.patch()` to safely deploy breaking changes to workflow code. Breaking changes alter which steps run or their order, which can cause recovery failures.
+
+**Incorrect (breaking change without patching):**
+
+```typescript
+// BEFORE: original workflow
+async function workflowFn() {
+  await foo();
+  await bar();
+}
+const workflow = DBOS.registerWorkflow(workflowFn);
+
+// AFTER: breaking change - recovery will fail for in-progress workflows!
+async function workflowFn() {
+  await baz(); // Changed step
+  await bar();
+}
+const workflow = DBOS.registerWorkflow(workflowFn);
+```
+
+**Correct (using patch):**
+
+```typescript
+async function workflowFn() {
+  if (await DBOS.patch("use-baz")) {
+    await baz(); // New workflows run this
+  } else {
+    await foo(); // Old workflows continue with original code
+  }
+  await bar();
+}
+const workflow = DBOS.registerWorkflow(workflowFn);
+```
+
+`DBOS.patch()` returns `true` for new workflows and `false` for workflows that started before the patch.
+
+**Deprecating patches (after all old workflows complete):**
+
+```typescript
+async function workflowFn() {
+  if (await DBOS.deprecatePatch("use-baz")) { // Always returns true
+    await baz();
+  }
+  await bar();
+}
+const workflow = DBOS.registerWorkflow(workflowFn);
+```
+
+**Removing patches (after all workflows using deprecatePatch complete):**
+
+```typescript
+async function workflowFn() {
+  await baz();
+  await bar();
+}
+const workflow = DBOS.registerWorkflow(workflowFn);
+```
+
+Lifecycle: `patch()` → deploy → wait for old workflows → `deprecatePatch()` → deploy → wait → remove patch entirely.
+
+Use `DBOS.listWorkflows` to check for active old workflows before deprecating or removing patches.
+
+Reference: [Patching](https://docs.dbos.dev/typescript/tutorials/upgrading-workflows#patching)

package/skills/dbos-typescript/references/advanced-versioning.md

@@ -0,0 +1,61 @@
+---
+title: Use Versioning for Blue-Green Deployments
+impact: LOW
+impactDescription: Enables safe deployment of new code versions alongside old ones
+tags: advanced, versioning, blue-green, deployment
+---
+
+## Use Versioning for Blue-Green Deployments
+
+Set `applicationVersion` in configuration to tag workflows with a version. DBOS only recovers workflows matching the current application version, preventing code mismatches during recovery.
+
+**Incorrect (deploying new code that breaks in-progress workflows):**
+
+```typescript
+DBOS.setConfig({
+  name: "my-app",
+  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  // No version set - all workflows recovered regardless of code version
+});
+```
+
+**Correct (versioned deployment):**
+
+```typescript
+DBOS.setConfig({
+  name: "my-app",
+  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  applicationVersion: "2.0.0",
+});
+```
+
+By default, the application version is automatically computed from a hash of workflow source code. Set it explicitly for more control.
+
+**Blue-green deployment strategy:**
+
+1. Deploy new version (v2) alongside old version (v1)
+2. Direct new traffic to v2 processes
+3. Let v1 processes "drain" (complete in-progress workflows)
+4. Check for remaining v1 workflows:
+
+```typescript
+const oldWorkflows = await DBOS.listWorkflows({
+  applicationVersion: "1.0.0",
+  status: "PENDING",
+});
+```
+
+5. Once all v1 workflows are complete, retire v1 processes
+
+**Fork to new version (for stuck workflows):**
+
+```typescript
+// Fork a workflow from a failed step to run on the new version
+const handle = await DBOS.forkWorkflow<string>(
+  workflowID,
+  failedStepID,
+  { applicationVersion: "2.0.0" }
+);
+```
+
+Reference: [Versioning](https://docs.dbos.dev/typescript/tutorials/upgrading-workflows#versioning)