@ngxtm/devkit 3.14.0 → 3.16.0

package/skills/dbos-typescript/references/test-setup.md

@@ -0,0 +1,104 @@
+---
+title: Use Proper Test Setup for DBOS
+impact: LOW-MEDIUM
+impactDescription: Ensures consistent test results with proper DBOS lifecycle management
+tags: testing, jest, setup, integration, mock
+---
+
+## Use Proper Test Setup for DBOS
+
+DBOS applications can be tested with unit tests (mocking DBOS) or integration tests (real Postgres database).
+
+**Incorrect (no lifecycle management between tests):**
+
+```typescript
+// Tests share state - results are inconsistent!
+describe("tests", () => {
+  it("test one", async () => {
+    await myWorkflow("input");
+  });
+  it("test two", async () => {
+    // Previous test's state leaks into this test
+    await myWorkflow("input");
+  });
+});
+```
+
+**Correct (unit testing with mocks):**
+
+```typescript
+// Mock DBOS - no Postgres required
+jest.mock("@dbos-inc/dbos-sdk", () => ({
+  DBOS: {
+    registerWorkflow: jest.fn((fn) => fn),
+    runStep: jest.fn((fn) => fn()),
+    setEvent: jest.fn(),
+    recv: jest.fn(),
+    startWorkflow: jest.fn(),
+    workflowID: "test-workflow-id",
+  },
+}));
+
+describe("workflow unit tests", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should process data", async () => {
+    jest.mocked(DBOS.recv).mockResolvedValue("success");
+    await myWorkflow("input");
+    expect(DBOS.setEvent).toHaveBeenCalledWith("status", "done");
+  });
+});
+```
+
+Mock `registerWorkflow` to return the function directly (not wrapped with durable workflow code).
+
+**Correct (integration testing with Postgres):**
+
+```typescript
+import { DBOS, DBOSConfig } from "@dbos-inc/dbos-sdk";
+import { Client } from "pg";
+
+async function resetDatabase(databaseUrl: string) {
+  const dbName = new URL(databaseUrl).pathname.slice(1);
+  const postgresDatabaseUrl = new URL(databaseUrl);
+  postgresDatabaseUrl.pathname = "/postgres";
+  const client = new Client({ connectionString: postgresDatabaseUrl.toString() });
+  await client.connect();
+  try {
+    await client.query(`DROP DATABASE IF EXISTS ${dbName} WITH (FORCE)`);
+    await client.query(`CREATE DATABASE ${dbName}`);
+  } finally {
+    await client.end();
+  }
+}
+
+describe("integration tests", () => {
+  beforeEach(async () => {
+    const databaseUrl = process.env.DBOS_TEST_DATABASE_URL;
+    if (!databaseUrl) throw Error("DBOS_TEST_DATABASE_URL must be set");
+    await DBOS.shutdown();
+    await resetDatabase(databaseUrl);
+    DBOS.setConfig({ name: "my-integration-test", systemDatabaseUrl: databaseUrl });
+    await DBOS.launch();
+  }, 10000);
+
+  afterEach(async () => {
+    await DBOS.shutdown();
+  });
+
+  it("should complete workflow", async () => {
+    const result = await myWorkflow("test-input");
+    expect(result).toBe("expected-output");
+  });
+});
+```
+
+Key points:
+- Call `DBOS.shutdown()` before resetting and reconfiguring
+- Reset the database between tests for isolation
+- Set a generous `beforeEach` timeout (10s) for database setup
+- Use `DBOS.shutdown({ deregister: true })` if re-registering functions
+
+Reference: [Testing & Mocking](https://docs.dbos.dev/typescript/tutorials/testing)

package/skills/dbos-typescript/references/workflow-background.md

@@ -0,0 +1,54 @@
+---
+title: Start Workflows in Background
+impact: CRITICAL
+impactDescription: Background workflows enable reliable async processing
+tags: workflow, background, handle, async
+---
+
+## Start Workflows in Background
+
+Use `DBOS.startWorkflow` to start a workflow in the background and get a handle to track it. The workflow is guaranteed to run to completion even if the app is interrupted.
+
+**Incorrect (no way to track background work):**
+
+```typescript
+async function processDataFn(data: string) {
+  // ...
+}
+const processData = DBOS.registerWorkflow(processDataFn);
+
+// Fire and forget - no way to track or get result
+processData(data);
+```
+
+**Correct (using startWorkflow):**
+
+```typescript
+async function processDataFn(data: string) {
+  return "processed: " + data;
+}
+const processData = DBOS.registerWorkflow(processDataFn);
+
+async function main() {
+  // Start workflow in background, get handle
+  const handle = await DBOS.startWorkflow(processData)("input");
+
+  // Get the workflow ID
+  console.log(handle.workflowID);
+
+  // Wait for result
+  const result = await handle.getResult();
+
+  // Check status
+  const status = await handle.getStatus();
+}
+```
+
+Retrieve a handle later by workflow ID:
+
+```typescript
+const handle = DBOS.retrieveWorkflow<string>(workflowID);
+const result = await handle.getResult();
+```
+
+Reference: [Starting Workflows in Background](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#starting-workflows-in-the-background)

package/skills/dbos-typescript/references/workflow-constraints.md

@@ -0,0 +1,65 @@
+---
+title: Follow Workflow Constraints
+impact: CRITICAL
+impactDescription: Violating constraints breaks recovery and durability guarantees
+tags: workflow, constraints, rules, best-practices
+---
+
+## Follow Workflow Constraints
+
+Workflows have specific constraints to maintain durability guarantees. Violating them can break recovery.
+
+**Incorrect (starting workflows from steps):**
+
+```typescript
+async function myStep() {
+  // Don't start workflows from steps!
+  await DBOS.startWorkflow(otherWorkflow)();
+}
+
+async function myOtherStep() {
+  // Don't call recv from steps!
+  const msg = await DBOS.recv("topic");
+}
+
+async function myWorkflowFn() {
+  await DBOS.runStep(myStep, { name: "myStep" });
+}
+```
+
+**Correct (workflow operations only from workflows):**
+
+```typescript
+async function fetchData() {
+  // Steps only do external operations
+  return await fetch("https://api.example.com").then(r => r.json());
+}
+
+async function myWorkflowFn() {
+  await DBOS.runStep(fetchData, { name: "fetchData" });
+  // Start child workflows from the parent workflow
+  await DBOS.startWorkflow(otherWorkflow)();
+  // Receive messages from the workflow
+  const msg = await DBOS.recv("topic");
+  // Set events from the workflow
+  await DBOS.setEvent("status", "done");
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+Additional constraints:
+- Don't modify global variables from workflows or steps
+- Steps in parallel must start in deterministic order:
+
+```typescript
+// CORRECT - deterministic start order
+const results = await Promise.allSettled([
+  DBOS.runStep(() => step1("arg1"), { name: "step1" }),
+  DBOS.runStep(() => step2("arg2"), { name: "step2" }),
+  DBOS.runStep(() => step3("arg3"), { name: "step3" }),
+]);
+```
+
+Use `Promise.allSettled` instead of `Promise.all` to safely handle errors without crashing the Node.js process.
+
+Reference: [Workflow Guarantees](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#workflow-guarantees)

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

@@ -0,0 +1,57 @@
+---
+title: Cancel, Resume, and Fork Workflows
+impact: CRITICAL
+impactDescription: Enables operational control over long-running workflows
+tags: workflow, cancel, resume, fork, management
+---
+
+## Cancel, Resume, and Fork Workflows
+
+DBOS provides methods to cancel, resume, and fork workflows for operational control.
+
+**Incorrect (no way to handle stuck or failed workflows):**
+
+```typescript
+// Workflow is stuck or failed - no recovery mechanism
+const handle = await DBOS.startWorkflow(processTask)("data");
+// If the workflow fails, there's no way to retry or recover
+```
+
+**Correct (using cancel, resume, and fork):**
+
+```typescript
+// Cancel a workflow - stops at its next step
+await DBOS.cancelWorkflow(workflowID);
+
+// Resume from the last completed step
+const handle = await DBOS.resumeWorkflow<string>(workflowID);
+const result = await handle.getResult();
+```
+
+Cancellation sets the workflow status to `CANCELLED` and preempts execution at the beginning of the next step. Cancelling also cancels all child workflows.
+
+Resume restarts a workflow from its last completed step. Use this for workflows that are cancelled or have exceeded their maximum recovery attempts. You can also use this to start an enqueued workflow immediately, bypassing its queue.
+
+Fork a workflow from a specific step:
+
+```typescript
+// List steps to find the right step ID
+const steps = await DBOS.listWorkflowSteps(workflowID);
+// steps[i].functionID is the step's ID
+
+// Fork from a specific step
+const forkHandle = await DBOS.forkWorkflow<string>(
+  workflowID,
+  startStep,
+  {
+    newWorkflowID: "new-wf-id",
+    applicationVersion: "2.0.0",
+    timeoutMS: 60000,
+  }
+);
+const forkResult = await forkHandle.getResult();
+```
+
+Forking creates a new workflow with a new ID, copying the original workflow's inputs and step outputs up to the selected step. Useful for recovering from downstream service outages or patching workflows that failed due to a bug.
+
+Reference: [Workflow Management](https://docs.dbos.dev/typescript/tutorials/workflow-management)

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

@@ -0,0 +1,54 @@
+---
+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):**
+
+```typescript
+async function exampleWorkflowFn() {
+  // Random value in workflow breaks recovery!
+  // On replay, Math.random() returns a different value,
+  // so the workflow may take a different branch.
+  const choice = Math.random() > 0.5 ? 1 : 0;
+  if (choice === 0) {
+    await stepOne();
+  } else {
+    await stepTwo();
+  }
+}
+const exampleWorkflow = DBOS.registerWorkflow(exampleWorkflowFn);
+```
+
+**Correct (non-determinism in step):**
+
+```typescript
+async function exampleWorkflowFn() {
+  // Step result is checkpointed - replay uses the saved value
+  const choice = await DBOS.runStep(
+    () => Promise.resolve(Math.random() > 0.5 ? 1 : 0),
+    { name: "generateChoice" }
+  );
+  if (choice === 0) {
+    await stepOne();
+  } else {
+    await stepTwo();
+  }
+}
+const exampleWorkflow = DBOS.registerWorkflow(exampleWorkflowFn);
+```
+
+Non-deterministic operations that must be in steps:
+- Random number generation (use `DBOS.randomUUID()` for UUIDs)
+- Getting current time (use `DBOS.now()` for timestamps)
+- Accessing external APIs
+- Reading files
+- Database queries (use transactions or steps)
+
+Reference: [Workflow Determinism](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#determinism)

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

@@ -0,0 +1,70 @@
+---
+title: List and Inspect Workflows
+impact: CRITICAL
+impactDescription: Enables monitoring and debugging of workflow executions
+tags: workflow, list, inspect, status, monitoring
+---
+
+## List and Inspect Workflows
+
+Use `DBOS.listWorkflows` to query workflow executions by status, name, time range, and other criteria.
+
+**Incorrect (no monitoring of workflow state):**
+
+```typescript
+// Start workflow with no way to check on it later
+await DBOS.startWorkflow(processTask)("data");
+// If something goes wrong, no way to find or debug it
+```
+
+**Correct (listing and inspecting workflows):**
+
+```typescript
+// List workflows by status
+const erroredWorkflows = await DBOS.listWorkflows({
+  status: "ERROR",
+});
+
+for (const wf of erroredWorkflows) {
+  console.log(`Workflow ${wf.workflowID}: ${wf.workflowName} - ${wf.error}`);
+}
+```
+
+List workflows with multiple filters:
+
+```typescript
+const workflows = await DBOS.listWorkflows({
+  workflowName: "processOrder",
+  status: "SUCCESS",
+  limit: 100,
+  sortDesc: true,
+  loadOutput: true,
+});
+```
+
+List enqueued workflows:
+
+```typescript
+const queued = await DBOS.listQueuedWorkflows({
+  queueName: "task_queue",
+});
+```
+
+List workflow steps:
+
+```typescript
+const steps = await DBOS.listWorkflowSteps(workflowID);
+if (steps) {
+  for (const step of steps) {
+    console.log(`Step ${step.functionID}: ${step.name}`);
+    if (step.error) console.log(`  Error: ${step.error}`);
+    if (step.childWorkflowID) console.log(`  Child: ${step.childWorkflowID}`);
+  }
+}
+```
+
+Workflow status values: `ENQUEUED`, `PENDING`, `SUCCESS`, `ERROR`, `CANCELLED`, `RETRIES_EXCEEDED`
+
+To optimize performance, set `loadInput: false` and `loadOutput: false` when you don't need workflow inputs or outputs.
+
+Reference: [Workflow Management](https://docs.dbos.dev/typescript/tutorials/workflow-management)

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

@@ -0,0 +1,39 @@
+---
+title: Set Workflow Timeouts
+impact: CRITICAL
+impactDescription: Prevents workflows from running indefinitely
+tags: workflow, timeout, cancellation, duration
+---
+
+## Set Workflow Timeouts
+
+Set a timeout for a workflow by passing `timeoutMS` to `DBOS.startWorkflow`. When the timeout expires, the workflow and all its children are cancelled.
+
+**Incorrect (no timeout for potentially long workflow):**
+
+```typescript
+// No timeout - could run indefinitely
+const handle = await DBOS.startWorkflow(processTask)("data");
+```
+
+**Correct (with timeout):**
+
+```typescript
+async function processTaskFn(data: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+// Timeout after 5 minutes (in milliseconds)
+const handle = await DBOS.startWorkflow(processTask, {
+  timeoutMS: 5 * 60 * 1000,
+})("data");
+```
+
+Key timeout behaviors:
+- Timeouts are **start-to-completion**: the timeout begins when the workflow starts execution, not when it's enqueued
+- Timeouts are **durable**: they persist across restarts, so workflows can have very long timeouts (hours, days, weeks)
+- Cancellation happens at the **beginning of the next step** - the current step completes first
+- Cancelling a workflow also cancels all **child workflows**
+
+Reference: [Workflow Timeouts](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#workflow-timeouts)

package/skills/dbt-transformation-patterns/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: dbt-transformation-patterns
-description: Master dbt (data build tool) for analytics engineering with model organization, testing, documentation, and incremental strategies. Use when building data transformations, creating data models, or implementing analytics engineering best practices.
+description: "Master dbt (data build tool) for analytics engineering with model organization, testing, documentation, and incremental strategies. Use when building data transformations, creating data models, or ..."
+risk: unknown
+source: community
 ---
 
 # dbt Transformation Patterns

package/skills/ddd-context-mapping/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ddd-context-mapping
+description: "Map relationships between bounded contexts and define integration contracts using DDD context mapping patterns."
+risk: safe
+source: self
+tags: [ddd, context-map, anti-corruption-layer, integration]
+---
+
+# DDD Context Mapping
+
+## Use this skill when
+
+- Defining integration patterns between bounded contexts.
+- Preventing domain leakage across service boundaries.
+- Planning anti-corruption layers during migration.
+- Clarifying upstream and downstream ownership for contracts.
+
+## Do not use this skill when
+
+- You have a single-context system with no integrations.
+- You only need internal class design.
+- You are selecting cloud infrastructure tooling.
+
+## Instructions
+
+1. List all context pairs and dependency direction.
+2. Choose relationship patterns per pair.
+3. Define translation rules and ownership boundaries.
+4. Add failure modes, fallback behavior, and versioning policy.
+
+If detailed mapping structures are needed, open `references/context-map-patterns.md`.
+
+## Output requirements
+
+- Relationship map for all context pairs
+- Contract ownership matrix
+- Translation and anti-corruption decisions
+- Known coupling risks and mitigation plan
+
+## Examples
+
+```text
+Use @ddd-context-mapping to define how Checkout integrates with Billing,
+Inventory, and Fraud contexts, including ACL and contract ownership.
+```
+
+## Limitations
+
+- This skill does not replace API-level schema design.
+- It does not guarantee organizational alignment by itself.
+- It should be revisited when team ownership changes.

package/skills/ddd-context-mapping/references/context-map-patterns.md

@@ -0,0 +1,25 @@
+# Context Mapping Patterns
+
+## Common relationship patterns
+
+- Partnership
+- Shared Kernel
+- Customer-Supplier
+- Conformist
+- Anti-Corruption Layer
+- Open Host Service
+- Published Language
+
+## Mapping template
+
+| Upstream context | Downstream context | Pattern | Contract owner | Translation needed |
+| --- | --- | --- | --- | --- |
+| Billing | Checkout | Customer-Supplier | Billing | Yes |
+| Identity | Checkout | Conformist | Identity | No |
+
+## ACL checklist
+
+- Define canonical domain model for receiving context.
+- Translate external terms into local ubiquitous language.
+- Keep ACL code at boundary, not inside domain core.
+- Add contract tests for mapped behavior.

package/skills/ddd-strategic-design/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ddd-strategic-design
+description: "Design DDD strategic artifacts including subdomains, bounded contexts, and ubiquitous language for complex business domains."
+risk: safe
+source: self
+tags: [ddd, strategic-design, bounded-context, ubiquitous-language]
+---
+
+# DDD Strategic Design
+
+## Use this skill when
+
+- Defining core, supporting, and generic subdomains.
+- Splitting a monolith or service landscape by domain boundaries.
+- Aligning teams and ownership with bounded contexts.
+- Building a shared ubiquitous language with domain experts.
+
+## Do not use this skill when
+
+- The domain model is stable and already well bounded.
+- You need tactical code patterns only.
+- The task is purely infrastructure or UI oriented.
+
+## Instructions
+
+1. Extract domain capabilities and classify subdomains.
+2. Define bounded contexts around consistency and ownership.
+3. Establish a ubiquitous language glossary and anti-terms.
+4. Capture context boundaries in ADRs before implementation.
+
+If detailed templates are needed, open `references/strategic-design-template.md`.
+
+## Required artifacts
+
+- Subdomain classification table
+- Bounded context catalog
+- Glossary with canonical terms
+- Boundary decisions with rationale
+
+## Examples
+
+```text
+Use @ddd-strategic-design to map our commerce domain into bounded contexts,
+classify subdomains, and propose team ownership.
+```
+
+## Limitations
+
+- This skill does not produce executable code.
+- It cannot infer business truth without stakeholder input.
+- It should be followed by tactical design before implementation.

package/skills/ddd-strategic-design/references/strategic-design-template.md

@@ -0,0 +1,22 @@
+# Strategic Design Template
+
+## Subdomain classification
+
+| Capability | Subdomain type | Why | Owner team |
+| --- | --- | --- | --- |
+| Pricing | Core | Differentiates business value | Commerce |
+| Identity | Supporting | Needed but not differentiating | Platform |
+
+## Bounded context catalog
+
+| Context | Responsibility | Upstream dependencies | Downstream consumers |
+| --- | --- | --- | --- |
+| Catalog | Product data lifecycle | Supplier feed | Checkout, Search |
+| Checkout | Order placement and payment authorization | Catalog, Pricing | Fulfillment, Billing |
+
+## Ubiquitous language
+
+| Term | Definition | Context |
+| --- | --- | --- |
+| Order | Confirmed purchase request | Checkout |
+| Reservation | Temporary inventory hold | Fulfillment |

package/skills/ddd-tactical-patterns/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ddd-tactical-patterns
+description: "Apply DDD tactical patterns in code using entities, value objects, aggregates, repositories, and domain events with explicit invariants."
+risk: safe
+source: self
+tags: [ddd, tactical, aggregates, value-objects, domain-events]
+---
+
+# DDD Tactical Patterns
+
+## Use this skill when
+
+- Translating domain rules into code structures.
+- Designing aggregate boundaries and invariants.
+- Refactoring an anemic model into behavior-rich domain objects.
+- Defining repository contracts and domain event boundaries.
+
+## Do not use this skill when
+
+- You are still defining strategic boundaries.
+- The task is only API documentation or UI layout.
+- Full DDD complexity is not justified.
+
+## Instructions
+
+1. Identify invariants first and design aggregates around them.
+2. Model immutable value objects for validated concepts.
+3. Keep domain behavior in domain objects, not controllers.
+4. Emit domain events for meaningful state transitions.
+5. Keep repositories at aggregate root boundaries.
+
+If detailed checklists are needed, open `references/tactical-checklist.md`.
+
+## Example
+
+```typescript
+class Order {
+  private status: "draft" | "submitted" = "draft";
+
+  submit(itemsCount: number): void {
+    if (itemsCount === 0) throw new Error("Order cannot be submitted empty");
+    if (this.status !== "draft") throw new Error("Order already submitted");
+    this.status = "submitted";
+  }
+}
+```
+
+## Limitations
+
+- This skill does not define deployment architecture.
+- It does not choose databases or transport protocols.
+- It should be paired with testing patterns for invariant coverage.

package/skills/ddd-tactical-patterns/references/tactical-checklist.md

@@ -0,0 +1,25 @@
+# Tactical Pattern Checklist
+
+## Aggregate design
+
+- One aggregate root per transaction boundary
+- Invariants enforced inside aggregate methods
+- Avoid cross-aggregate synchronous consistency rules
+
+## Value objects
+
+- Immutable by default
+- Validation at construction
+- Equality by value, not identity
+
+## Repositories
+
+- Persist and load aggregate roots only
+- Expose domain-friendly query methods
+- Avoid leaking ORM entities into domain layer
+
+## Domain events
+
+- Past-tense event names (for example, `OrderSubmitted`)
+- Include minimal, stable event payloads
+- Version event schema before breaking changes