@acmekit/acmekit 2.13.84 → 2.13.86

package/dist/templates/app/.claude/agents/test-writer.md

@@ -382,6 +382,74 @@ integrationTestRunner<IPostModuleService>({
 
 ---
 
+## Unit Test Template (No Framework Bootstrap)
+
+For providers, utilities, and standalone classes. Uses plain Jest with `jest.mock`.
+
+**CRITICAL — jest.mock hoisting:** `jest.mock()` factories are hoisted above `const`/`let` by SWC. Never reference file-level variables inside a factory. Create mocks INSIDE the factory and access via `require()`.
+
+```typescript
+// Provider unit test pattern
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  let provider: MyProvider
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
+
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
+    })
+  })
+
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
+
+    it("should reject missing required option", () => {
+      expect(() => MyProvider.validateOptions({})).toThrow()
+    })
+  })
+
+  describe("doSomething", () => {
+    it("should delegate to SDK", async () => {
+      sdkMocks.doThing.mockResolvedValue({ success: true })
+      const result = await provider.doSomething({ input: "test" })
+      expect(result.success).toBe(true)
+    })
+  })
+})
+```
+
+**Timer mocking:** If code under test uses `setTimeout` or `sleep()`, use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or mock the sleep method.
+
+**SWC regex:** Complex regex literals may fail. Use `new RegExp("...")` instead.
+
+**Error paths:** Read the implementation to check whether errors are thrown or returned. Don't assume from the return type.
+
+---
+
 ## Asserting Domain Events (module mode)
 
 ```typescript
@@ -486,3 +554,7 @@ it("should emit post.created event", async () => {
 - Direct workflow execution: `workflow(getContainer()).run({ input })`
 - `waitSubscribersExecution` promise BEFORE triggering event
 - NEVER use JSDoc blocks or type casts in test files
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error
+- **Mock timers or sleep** when code under test has delays — prevents timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser has edge cases

package/dist/templates/app/.claude/rules/testing.md

@@ -22,6 +22,10 @@ paths:
 
 **`.rejects.toThrow()` DOES work for service errors** (e.g., `service.retrievePost("bad-id")`). Services throw real `Error` instances. Only workflow errors are serialized.
 
+**jest.mock factories are hoisted.** `jest.mock()` runs BEFORE `const`/`let` declarations. Never reference file-level variables inside a `jest.mock()` factory — see "Unit Tests" section below.
+
+**Always add `jest.clearAllMocks()` in `beforeEach`.** Mock state leaks between test blocks. Without explicit cleanup, assertions on mock call counts fail from prior-test contamination.
+
 **Inline auth setup.** There is no `createAdminUser` helper. Resolve `Modules.USER`, `Modules.AUTH`, `Modules.API_KEY` from the container and create credentials directly in `beforeEach`.
 
 ---
@@ -248,11 +252,10 @@ integrationTestRunner({
 ### HTTP test lifecycle
 
 - `beforeAll`: boots full Express app (resolves plugins, runs migrations, starts HTTP server)
-- `beforeEach`: truncates all tables, re-runs module loaders, runs `createDefaultsWorkflow`
-- `afterEach`: **automatically calls `waitWorkflowExecutions()`** then `dbUtils.teardown()`
+- `beforeEach`: **automatically calls `waitWorkflowExecutions()`** from the previous test, then truncates all tables, re-runs module loaders, runs `createDefaultsWorkflow` (first test skips reset — state is already fresh after setup)
 - `afterAll`: drops DB, shuts down Express
 
-**IMPORTANT:** The runner calls `waitWorkflowExecutions()` automatically in `afterEach`. You do NOT need to call it in your tests unless you need workflow results BETWEEN two API calls in the same test.
+**IMPORTANT:** The runner calls `waitWorkflowExecutions()` automatically during the reset phase (before each subsequent test). You do NOT need to call it in your tests unless you need workflow results BETWEEN two API calls in the same test.
 
 ---
 
@@ -719,6 +722,188 @@ getContainer().resolve("blogModuleService")  // ❌
 
 ---
 
+## Unit Tests (No Framework Bootstrap)
+
+For providers, utility functions, and standalone classes that don't need the database or AcmeKit container. Uses plain Jest — no `integrationTestRunner`.
+
+**File naming:** `src/**/__tests__/<name>.unit.spec.ts` — matches `TEST_TYPE=unit` in `jest.config.js`.
+
+### jest.mock Hoisting (Temporal Dead Zone)
+
+`jest.mock()` factories are **hoisted above all `const`/`let` declarations** by SWC/Babel. Referencing a file-level `const` inside a `jest.mock()` factory causes `ReferenceError: Cannot access before initialization`.
+
+```typescript
+// WRONG — TDZ error: mockSign is not yet initialized when factory runs
+const mockSign = jest.fn()
+jest.mock("tronweb", () => ({
+  TronWeb: jest.fn().mockImplementation(() => ({ trx: { sign: mockSign } })),
+}))
+
+// RIGHT — create mocks INSIDE the factory, expose via module return
+jest.mock("tronweb", () => {
+  const mocks = {
+    sign: jest.fn(),
+    isAddress: jest.fn().mockReturnValue(true),
+  }
+  const MockTronWeb = jest.fn().mockImplementation(() => ({
+    trx: { sign: mocks.sign },
+  }))
+  MockTronWeb.isAddress = mocks.isAddress
+  return { TronWeb: MockTronWeb, __mocks: mocks }
+})
+
+// Access mocks after jest.mock via require()
+const { __mocks: tronMocks } = require("tronweb")
+```
+
+**Rule:** All mock state must live INSIDE the `jest.mock()` factory or be accessed via `require()` after the mock is set up. Never reference file-level `const`/`let` from inside a `jest.mock()` factory.
+
+### Provider Unit Test Pattern
+
+Providers have a specific structure: constructor receives `(container, options)`, static `identifier`, optional static `validateOptions`. Test each part:
+
+```typescript
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  let provider: MyProvider
+
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
+
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
+    })
+  })
+
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
+
+    it("should reject missing required option", () => {
+      expect(() => MyProvider.validateOptions({})).toThrow()
+    })
+  })
+
+  describe("doSomething", () => {
+    it("should delegate to SDK", async () => {
+      sdkMocks.doThing.mockResolvedValue({ success: true })
+      const result = await provider.doSomething({ input: "test" })
+      expect(result.success).toBe(true)
+      expect(sdkMocks.doThing).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "test" })
+      )
+    })
+  })
+})
+```
+
+### Mock Cleanup Between Tests
+
+Mock state leaks between `describe` and `it` blocks. **Always add cleanup:**
+
+```typescript
+// Recommended: file-level cleanup
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+// Alternative: per-describe when different describes need different setups
+describe("feature A", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockFn.mockResolvedValue("A result")
+  })
+})
+```
+
+Without `jest.clearAllMocks()`, a mock called in one test still shows those calls in the next test:
+
+```typescript
+expect(mockSign).not.toHaveBeenCalled()  // FAILS — called by prior test
+```
+
+### Testing Code with Timers
+
+When code under test calls `setTimeout`, `setInterval`, or a `sleep()` function, tests time out or run slowly.
+
+```typescript
+// Option 1: Fake timers (for setTimeout/setInterval)
+beforeEach(() => {
+  jest.useFakeTimers()
+})
+afterEach(() => {
+  jest.useRealTimers()
+})
+it("should retry after delay", async () => {
+  const promise = provider.retryOperation()
+  await jest.advanceTimersByTimeAsync(3000)
+  const result = await promise
+  expect(result).toBeDefined()
+})
+
+// Option 2: Mock the sleep method (for custom sleep/delay functions)
+it("should complete without waiting", async () => {
+  jest.spyOn(provider as any, "sleep_").mockResolvedValue(undefined)
+  const result = await provider.longRunningOperation()
+  expect(result).toBeDefined()
+})
+```
+
+### SWC Regex Limitation
+
+SWC's regex parser fails on certain complex regex literals. If you get a `Syntax Error` from SWC on a line with a regex:
+
+```typescript
+// WRONG — SWC may fail to parse this
+const pattern = /^(\*|[0-9]+)(\/[0-9]+)?$|^\*\/[0-9]+$/
+
+// RIGHT — use RegExp constructor
+const pattern = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$|^\\*\\/[0-9]+$")
+```
+
+### Verifying Error Paths
+
+When testing error cases, **read the implementation** to determine whether the method throws or returns an error object. Don't assume from the return type alone.
+
+```typescript
+// If the method catches errors and returns { success: false }:
+const result = await provider.process(badInput)
+expect(result.success).toBe(false)
+
+// If the method throws (no internal try/catch on that path):
+await expect(provider.process(badInput)).rejects.toThrow("invalid")
+
+// If validation runs BEFORE a try/catch block:
+// validateInput() throws → not caught by the try/catch in process()
+await expect(provider.process(badInput)).rejects.toThrow("validation")
+```
+
+**Tip:** Look for `try/catch` blocks in the implementation. Code that runs BEFORE or OUTSIDE a `try/catch` throws directly. Code INSIDE a `try/catch` may return an error result instead.
+
+---
+
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
@@ -848,4 +1033,39 @@ import { ContainerRegistrationKeys } from "@acmekit/framework/utils"  // ❌ if
 
 // WRONG — type casts in tests
 const filtered = (operations as Array<{ status: string }>).filter(...)  // ❌
+
+// WRONG — referencing file-level const/let inside jest.mock factory (TDZ)
+const mockFn = jest.fn()
+jest.mock("lib", () => ({ thing: mockFn }))  // ❌ ReferenceError
+// RIGHT — create mocks inside factory, access via require()
+jest.mock("lib", () => {
+  const mocks = { thing: jest.fn() }
+  return { ...mocks, __mocks: mocks }
+})
+const { __mocks } = require("lib")
+
+// WRONG — no mock cleanup between tests
+describe("A", () => { it("calls mock", () => { mockFn() }) })
+describe("B", () => { it("mock is clean", () => {
+  expect(mockFn).not.toHaveBeenCalled()  // ❌ fails — leaked from A
+}) })
+// RIGHT — add beforeEach(() => jest.clearAllMocks())
+
+// WRONG — real timers in unit tests cause timeouts
+it("should process", async () => {
+  await relay.process(data)  // ❌ hangs — code calls sleep(3000) internally
+})
+// RIGHT — mock timers or sleep method
+jest.useFakeTimers()
+// or: jest.spyOn(relay as any, "sleep_").mockResolvedValue(undefined)
+
+// WRONG — complex regex literal that SWC can't parse
+const re = /^(\*|[0-9]+)(\/[0-9]+)?$/  // ❌ SWC Syntax Error
+// RIGHT
+const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
+
+// WRONG — assuming method returns error without reading implementation
+const result = await provider.process(bad)
+expect(result.success).toBe(false)  // ❌ actually throws
+// RIGHT — read implementation first to check if it throws or returns
 ```

package/dist/templates/app/.claude/skills/write-test/SKILL.md

@@ -238,6 +238,47 @@ integrationTestRunner({
 })
 ```
 
+#### Unit Test (No Framework Bootstrap)
+
+For providers, utilities, and standalone classes. **CRITICAL:** `jest.mock()` factories are hoisted above `const`/`let`. Create mocks INSIDE the factory, access via `require()`.
+
+```typescript
+jest.mock("external-sdk", () => {
+  const mocks = { doThing: jest.fn() }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  const mockContainer = {} as any
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it("should have correct identifier", () => {
+    expect(MyProvider.identifier).toBe("my-provider")
+  })
+
+  it("should delegate to SDK", async () => {
+    sdkMocks.doThing.mockResolvedValue({ success: true })
+    const provider = new MyProvider(mockContainer, { apiKey: "key" })
+    const result = await provider.doSomething({ input: "test" })
+    expect(result.success).toBe(true)
+  })
+})
+```
+
+**Timer mocking:** Use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or `jest.spyOn(instance, "sleep_").mockResolvedValue(undefined)`.
+
+**SWC regex:** Use `new RegExp("...")` instead of complex regex literals.
+
 #### Module Integration Test
 
 ```typescript
@@ -280,3 +321,8 @@ pnpm test:integration:http        # HTTP integration tests
 - Call `waitSubscribersExecution` BEFORE triggering the event
 - Import jobs/subscribers directly and call with container
 - Use realistic test data, not "test" or "foo"
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error (SWC/Babel hoisting)
+- **Mock timers or sleep** when code under test has delays — prevents test timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser fails on some patterns
+- **Read implementation to verify error paths** — check if errors are thrown vs returned

package/dist/templates/plugin/.claude/agents/test-writer.md

@@ -258,6 +258,15 @@ integrationTestRunner({
 
 **Fixtures (container-only):** `container`, `acmekitApp`, `MikroOrmWrapper`, `dbConfig`.
 
+**When plugin depends on other plugins:** Use `additionalPlugins` to load real peer plugins with their modules, migrations, and services. Only fall back to `skipDependencyValidation: true` + `injectedDependencies` mocks when peer plugins can't be installed.
+
+**When plugin has providers needing options:** Use `pluginModuleOptions` keyed by module name:
+```typescript
+pluginModuleOptions: {
+  myModule: { providers: [{ resolve: "./src/providers/my-provider", id: "my-id", options: { apiKey: "key" } }] },
+}
+```
+
 ---
 
 ## Subscriber Test Template (direct handler invocation)
@@ -392,6 +401,74 @@ integrationTestRunner<IGreetingModuleService>({
 
 ---
 
+## Unit Test Template (No Framework Bootstrap)
+
+For providers, utilities, and standalone classes. Uses plain Jest with `jest.mock`.
+
+**CRITICAL — jest.mock hoisting:** `jest.mock()` factories are hoisted above `const`/`let` by SWC. Never reference file-level variables inside a factory. Create mocks INSIDE the factory and access via `require()`.
+
+```typescript
+// Provider unit test pattern
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  let provider: MyProvider
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
+
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
+    })
+  })
+
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
+
+    it("should reject missing required option", () => {
+      expect(() => MyProvider.validateOptions({})).toThrow()
+    })
+  })
+
+  describe("doSomething", () => {
+    it("should delegate to SDK", async () => {
+      sdkMocks.doThing.mockResolvedValue({ success: true })
+      const result = await provider.doSomething({ input: "test" })
+      expect(result.success).toBe(true)
+    })
+  })
+})
+```
+
+**Timer mocking:** If code under test uses `setTimeout` or `sleep()`, use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or mock the sleep method.
+
+**SWC regex:** Complex regex literals may fail. Use `new RegExp("...")` instead.
+
+**Error paths:** Read the implementation to check whether errors are thrown or returned. Don't assume from the return type.
+
+---
+
 ## Asserting Domain Events (container-only mode)
 
 Plugin mode (without HTTP) injects `MockEventBusService`. Spy on the **prototype**, not an instance.
@@ -502,3 +579,7 @@ it("should emit greeting.created event", async () => {
 - Spy on `MockEventBusService.prototype` — not an instance
 - `jest.restoreAllMocks()` in `afterEach` when spying
 - NEVER use JSDoc blocks or type casts in test files
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error
+- **Mock timers or sleep** when code under test has delays — prevents timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser has edge cases

package/dist/templates/plugin/.claude/rules/testing.md

@@ -22,6 +22,10 @@ paths:
 
 **`.rejects.toThrow()` DOES work for service errors** (e.g., `service.retrievePost("bad-id")`). Services throw real `Error` instances. Only workflow errors are serialized.
 
+**jest.mock factories are hoisted.** `jest.mock()` runs BEFORE `const`/`let` declarations. Never reference file-level variables inside a `jest.mock()` factory — see "Unit Tests" section below.
+
+**Always add `jest.clearAllMocks()` in `beforeEach`.** Mock state leaks between test blocks. Without explicit cleanup, assertions on mock call counts fail from prior-test contamination.
+
 ---
 
 ## Test Runner Selection
@@ -124,8 +128,11 @@ integrationTestRunner({
 | `pluginPath` | `string` | **(required)** | Path to plugin root — always use `process.cwd()` |
 | `pluginOptions` | `Record<string, unknown>` | `{}` | Simulates host app plugin config |
 | `http` | `boolean` | `false` | Set `true` to boot full Express server for HTTP tests |
+| `additionalPlugins` | `Array<{ resolve, options? }>` | `[]` | Peer plugins to load alongside the plugin under test — real modules, migrations, services |
 | `additionalModules` | `Record<string, any>` | `{}` | Extra modules to load alongside the plugin |
 | `injectedDependencies` | `Record<string, any>` | `{}` | Mock services to register in the container |
+| `skipDependencyValidation` | `boolean` | `false` | Escape hatch: skip `definePlugin({ dependencies })` validation when peer plugins can't be installed |
+| `pluginModuleOptions` | `Record<string, Record<string, any>>` | `{}` | Per-module options keyed by module name (e.g., provider config) |
 | `dbName` | `string` | auto-generated | Override the computed DB name |
 | `schema` | `string` | `"public"` | Postgres schema |
 | `debug` | `boolean` | `false` | Enables DB query logging |
@@ -534,6 +541,255 @@ container.resolve("auth")  // ❌
 
 ---
 
+## Unit Tests (No Framework Bootstrap)
+
+For providers, utility functions, and standalone classes that don't need the database or AcmeKit container. Uses plain Jest — no `integrationTestRunner`.
+
+**File naming:** `src/**/__tests__/<name>.unit.spec.ts` — matches `TEST_TYPE=unit` in `jest.config.js`.
+
+### jest.mock Hoisting (Temporal Dead Zone)
+
+`jest.mock()` factories are **hoisted above all `const`/`let` declarations** by SWC/Babel. Referencing a file-level `const` inside a `jest.mock()` factory causes `ReferenceError: Cannot access before initialization`.
+
+```typescript
+// WRONG — TDZ error: mockSign is not yet initialized when factory runs
+const mockSign = jest.fn()
+jest.mock("tronweb", () => ({
+  TronWeb: jest.fn().mockImplementation(() => ({ trx: { sign: mockSign } })),
+}))
+
+// RIGHT — create mocks INSIDE the factory, expose via module return
+jest.mock("tronweb", () => {
+  const mocks = {
+    sign: jest.fn(),
+    isAddress: jest.fn().mockReturnValue(true),
+  }
+  const MockTronWeb = jest.fn().mockImplementation(() => ({
+    trx: { sign: mocks.sign },
+  }))
+  MockTronWeb.isAddress = mocks.isAddress
+  return { TronWeb: MockTronWeb, __mocks: mocks }
+})
+
+// Access mocks after jest.mock via require()
+const { __mocks: tronMocks } = require("tronweb")
+```
+
+**Rule:** All mock state must live INSIDE the `jest.mock()` factory or be accessed via `require()` after the mock is set up. Never reference file-level `const`/`let` from inside a `jest.mock()` factory.
+
+### Provider Unit Test Pattern
+
+Providers have a specific structure: constructor receives `(container, options)`, static `identifier`, optional static `validateOptions`. Test each part:
+
+```typescript
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  let provider: MyProvider
+
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
+
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
+    })
+  })
+
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
+
+    it("should reject missing required option", () => {
+      expect(() => MyProvider.validateOptions({})).toThrow()
+    })
+  })
+
+  describe("doSomething", () => {
+    it("should delegate to SDK", async () => {
+      sdkMocks.doThing.mockResolvedValue({ success: true })
+      const result = await provider.doSomething({ input: "test" })
+      expect(result.success).toBe(true)
+      expect(sdkMocks.doThing).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "test" })
+      )
+    })
+  })
+})
+```
+
+### Mock Cleanup Between Tests
+
+Mock state leaks between `describe` and `it` blocks. **Always add cleanup:**
+
+```typescript
+// Recommended: file-level cleanup
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+// Alternative: per-describe when different describes need different setups
+describe("feature A", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockFn.mockResolvedValue("A result")
+  })
+})
+```
+
+Without `jest.clearAllMocks()`, a mock called in one test still shows those calls in the next test:
+
+```typescript
+expect(mockSign).not.toHaveBeenCalled()  // FAILS — called by prior test
+```
+
+### Testing Code with Timers
+
+When code under test calls `setTimeout`, `setInterval`, or a `sleep()` function, tests time out or run slowly.
+
+```typescript
+// Option 1: Fake timers (for setTimeout/setInterval)
+beforeEach(() => {
+  jest.useFakeTimers()
+})
+afterEach(() => {
+  jest.useRealTimers()
+})
+it("should retry after delay", async () => {
+  const promise = provider.retryOperation()
+  await jest.advanceTimersByTimeAsync(3000)
+  const result = await promise
+  expect(result).toBeDefined()
+})
+
+// Option 2: Mock the sleep method (for custom sleep/delay functions)
+it("should complete without waiting", async () => {
+  jest.spyOn(provider as any, "sleep_").mockResolvedValue(undefined)
+  const result = await provider.longRunningOperation()
+  expect(result).toBeDefined()
+})
+```
+
+### SWC Regex Limitation
+
+SWC's regex parser fails on certain complex regex literals. If you get a `Syntax Error` from SWC on a line with a regex:
+
+```typescript
+// WRONG — SWC may fail to parse this
+const pattern = /^(\*|[0-9]+)(\/[0-9]+)?$|^\*\/[0-9]+$/
+
+// RIGHT — use RegExp constructor
+const pattern = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$|^\\*\\/[0-9]+$")
+```
+
+### Verifying Error Paths
+
+When testing error cases, **read the implementation** to determine whether the method throws or returns an error object. Don't assume from the return type alone.
+
+```typescript
+// If the method catches errors and returns { success: false }:
+const result = await provider.process(badInput)
+expect(result.success).toBe(false)
+
+// If the method throws (no internal try/catch on that path):
+await expect(provider.process(badInput)).rejects.toThrow("invalid")
+
+// If validation runs BEFORE a try/catch block:
+// validateInput() throws → not caught by the try/catch in process()
+await expect(provider.process(badInput)).rejects.toThrow("validation")
+```
+
+**Tip:** Look for `try/catch` blocks in the implementation. Code that runs BEFORE or OUTSIDE a `try/catch` throws directly. Code INSIDE a `try/catch` may return an error result instead.
+
+---
+
+## Testing Plugins with Dependencies
+
+When your plugin depends on other plugins (declared in `definePlugin({ dependencies })`), use `additionalPlugins` to load them alongside the plugin under test. This boots real modules, runs real migrations, and registers real services — the same as production:
+
+```typescript
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  additionalPlugins: [
+    { resolve: "@acmekit/plugin-reviews" },
+    { resolve: "@acmekit/plugin-loyalty", options: { tier: "gold" } },
+  ],
+  testSuite: ({ container }) => {
+    // container has REAL services from all plugins
+    it("uses review service", async () => {
+      const reviewService = container.resolve(REVIEW_MODULE)
+      const reviews = await reviewService.listReviews()
+      expect(reviews).toBeDefined()
+    })
+  },
+})
+```
+
+**Escape hatch:** When peer plugins genuinely can't be installed (e.g., CI without optional deps), use `skipDependencyValidation` to bypass validation and mock the services manually:
+
+```typescript
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  skipDependencyValidation: true,
+  injectedDependencies: {
+    // Mock services your plugin expects from peer plugins
+    peerModuleService: { list: jest.fn().mockResolvedValue([]) },
+  },
+  testSuite: ({ container }) => { ... },
+})
+```
+
+> **Prefer `additionalPlugins` over `skipDependencyValidation` + mocks.** Mocked services can silently drift from the real API — tests pass but production breaks.
+
+## Configuring Providers in Plugin Tests
+
+Use `pluginModuleOptions` to pass per-module options (e.g., provider configuration) keyed by module name:
+
+```typescript
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  pluginModuleOptions: {
+    tron: {
+      providers: [
+        {
+          resolve: "./src/providers/energy/own-pool",
+          id: "own-pool",
+          options: { apiKey: "test-key" },
+        },
+      ],
+    },
+  },
+  testSuite: ({ container }) => { ... },
+})
+```
+
+`pluginModuleOptions` is merged into the discovered module config AFTER `pluginOptions`, so module-specific options override plugin-level ones.
+
+---
+
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
@@ -624,4 +880,39 @@ import jwt from "jsonwebtoken"  // ❌
 { [CLIENT_API_KEY_HEADER]: token }
 
 // WRONG — unused imports, JSDoc blocks, type casts in tests
+
+// WRONG — referencing file-level const/let inside jest.mock factory (TDZ)
+const mockFn = jest.fn()
+jest.mock("lib", () => ({ thing: mockFn }))  // ❌ ReferenceError
+// RIGHT — create mocks inside factory, access via require()
+jest.mock("lib", () => {
+  const mocks = { thing: jest.fn() }
+  return { ...mocks, __mocks: mocks }
+})
+const { __mocks } = require("lib")
+
+// WRONG — no mock cleanup between tests
+describe("A", () => { it("calls mock", () => { mockFn() }) })
+describe("B", () => { it("mock is clean", () => {
+  expect(mockFn).not.toHaveBeenCalled()  // ❌ fails — leaked from A
+}) })
+// RIGHT — add beforeEach(() => jest.clearAllMocks())
+
+// WRONG — real timers in unit tests cause timeouts
+it("should process", async () => {
+  await relay.process(data)  // ❌ hangs — code calls sleep(3000) internally
+})
+// RIGHT — mock timers or sleep method
+jest.useFakeTimers()
+// or: jest.spyOn(relay as any, "sleep_").mockResolvedValue(undefined)
+
+// WRONG — complex regex literal that SWC can't parse
+const re = /^(\*|[0-9]+)(\/[0-9]+)?$/  // ❌ SWC Syntax Error
+// RIGHT
+const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
+
+// WRONG — assuming method returns error without reading implementation
+const result = await provider.process(bad)
+expect(result.success).toBe(false)  // ❌ actually throws
+// RIGHT — read implementation first to check if it throws or returns
 ```

package/dist/templates/plugin/.claude/skills/write-test/SKILL.md

@@ -275,6 +275,47 @@ integrationTestRunner({
 })
 ```
 
+#### Unit Test (No Framework Bootstrap)
+
+For providers, utilities, and standalone classes. **CRITICAL:** `jest.mock()` factories are hoisted above `const`/`let`. Create mocks INSIDE the factory, access via `require()`.
+
+```typescript
+jest.mock("external-sdk", () => {
+  const mocks = { doThing: jest.fn() }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
+
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  const mockContainer = {} as any
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it("should have correct identifier", () => {
+    expect(MyProvider.identifier).toBe("my-provider")
+  })
+
+  it("should delegate to SDK", async () => {
+    sdkMocks.doThing.mockResolvedValue({ success: true })
+    const provider = new MyProvider(mockContainer, { apiKey: "key" })
+    const result = await provider.doSomething({ input: "test" })
+    expect(result.success).toBe(true)
+  })
+})
+```
+
+**Timer mocking:** Use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or `jest.spyOn(instance, "sleep_").mockResolvedValue(undefined)`.
+
+**SWC regex:** Use `new RegExp("...")` instead of complex regex literals.
+
 #### Module Integration Test (isolated)
 
 ```typescript
@@ -315,9 +356,16 @@ pnpm test:integration:http          # Plugin HTTP tests
 - Always use `pluginPath: process.cwd()` — never hardcode paths
 - Container-only tests: access services via `container.resolve(MODULE_CONSTANT)` — no `api` fixture
 - HTTP tests: full auth setup with `generateJwtToken` + `ApiKeyType.CLIENT` — no `createAdminUser` helper
+- Plugin depends on other plugins: use `additionalPlugins: [{ resolve: "@acmekit/plugin-name" }]` to load real peers. Fall back to `skipDependencyValidation: true` + `injectedDependencies` only when peers can't be installed
+- Plugin providers need options: use `pluginModuleOptions: { moduleName: { providers: [...] } }`
 - Pass body directly: `api.post(url, body, headers)` — NOT `{ body: {...} }`
 - Use `.catch((e: any) => e)` for error assertions — axios throws on 4xx/5xx
 - Use `expect.objectContaining()` with `expect.any(String)` for IDs/timestamps
 - Test subscribers by importing handler directly and calling with `{ event, container }`
 - Test jobs by importing function directly and calling with `container`
 - Use realistic test data, not "test" or "foo"
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error (SWC/Babel hoisting)
+- **Mock timers or sleep** when code under test has delays — prevents test timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser fails on some patterns
+- **Read implementation to verify error paths** — check if errors are thrown vs returned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acmekit/acmekit",
-  "version": "2.13.84",
+  "version": "2.13.86",
   "description": "Generic application bootstrap and loaders for the AcmeKit framework",
   "main": "dist/index.js",
   "exports": {
@@ -49,45 +49,45 @@
     "test:integration": "../../node_modules/.bin/jest --passWithNoTests --forceExit --testPathPattern=\"src/.*/integration-tests/__tests__/.*\\.ts\""
   },
   "devDependencies": {
-    "@acmekit/framework": "2.13.84"
+    "@acmekit/framework": "2.13.86"
   },
   "dependencies": {
-    "@acmekit/admin-bundler": "2.13.84",
-    "@acmekit/analytics": "2.13.84",
-    "@acmekit/analytics-local": "2.13.84",
-    "@acmekit/analytics-posthog": "2.13.84",
-    "@acmekit/api-key": "2.13.84",
-    "@acmekit/auth": "2.13.84",
-    "@acmekit/auth-emailpass": "2.13.84",
-    "@acmekit/auth-github": "2.13.84",
-    "@acmekit/auth-google": "2.13.84",
-    "@acmekit/cache-inmemory": "2.13.84",
-    "@acmekit/cache-redis": "2.13.84",
-    "@acmekit/caching": "2.13.84",
-    "@acmekit/caching-redis": "2.13.84",
-    "@acmekit/core-flows": "2.13.84",
-    "@acmekit/event-bus-local": "2.13.84",
-    "@acmekit/event-bus-redis": "2.13.84",
-    "@acmekit/file": "2.13.84",
-    "@acmekit/file-local": "2.13.84",
-    "@acmekit/file-s3": "2.13.84",
-    "@acmekit/index": "2.13.84",
-    "@acmekit/link-modules": "2.13.84",
-    "@acmekit/locking": "2.13.84",
-    "@acmekit/locking-postgres": "2.13.84",
-    "@acmekit/locking-redis": "2.13.84",
-    "@acmekit/notification": "2.13.84",
-    "@acmekit/notification-local": "2.13.84",
-    "@acmekit/notification-sendgrid": "2.13.84",
-    "@acmekit/rbac": "2.13.84",
-    "@acmekit/secrets-aws": "2.13.84",
-    "@acmekit/secrets-local": "2.13.84",
-    "@acmekit/settings": "2.13.84",
-    "@acmekit/telemetry": "2.13.84",
-    "@acmekit/translation": "2.13.84",
-    "@acmekit/user": "2.13.84",
-    "@acmekit/workflow-engine-inmemory": "2.13.84",
-    "@acmekit/workflow-engine-redis": "2.13.84",
+    "@acmekit/admin-bundler": "2.13.86",
+    "@acmekit/analytics": "2.13.86",
+    "@acmekit/analytics-local": "2.13.86",
+    "@acmekit/analytics-posthog": "2.13.86",
+    "@acmekit/api-key": "2.13.86",
+    "@acmekit/auth": "2.13.86",
+    "@acmekit/auth-emailpass": "2.13.86",
+    "@acmekit/auth-github": "2.13.86",
+    "@acmekit/auth-google": "2.13.86",
+    "@acmekit/cache-inmemory": "2.13.86",
+    "@acmekit/cache-redis": "2.13.86",
+    "@acmekit/caching": "2.13.86",
+    "@acmekit/caching-redis": "2.13.86",
+    "@acmekit/core-flows": "2.13.86",
+    "@acmekit/event-bus-local": "2.13.86",
+    "@acmekit/event-bus-redis": "2.13.86",
+    "@acmekit/file": "2.13.86",
+    "@acmekit/file-local": "2.13.86",
+    "@acmekit/file-s3": "2.13.86",
+    "@acmekit/index": "2.13.86",
+    "@acmekit/link-modules": "2.13.86",
+    "@acmekit/locking": "2.13.86",
+    "@acmekit/locking-postgres": "2.13.86",
+    "@acmekit/locking-redis": "2.13.86",
+    "@acmekit/notification": "2.13.86",
+    "@acmekit/notification-local": "2.13.86",
+    "@acmekit/notification-sendgrid": "2.13.86",
+    "@acmekit/rbac": "2.13.86",
+    "@acmekit/secrets-aws": "2.13.86",
+    "@acmekit/secrets-local": "2.13.86",
+    "@acmekit/settings": "2.13.86",
+    "@acmekit/telemetry": "2.13.86",
+    "@acmekit/translation": "2.13.86",
+    "@acmekit/user": "2.13.86",
+    "@acmekit/workflow-engine-inmemory": "2.13.86",
+    "@acmekit/workflow-engine-redis": "2.13.86",
     "@inquirer/checkbox": "^2.3.11",
     "@inquirer/input": "^2.2.9",
     "boxen": "^5.0.1",
@@ -106,7 +106,7 @@
   },
   "peerDependencies": {
     "@acmekit/docs-bundler": "^2.13.42",
-    "@acmekit/framework": "2.13.84",
+    "@acmekit/framework": "2.13.86",
     "@jimsheen/yalc": "^1.2.2",
     "@swc/core": "^1.7.28",
     "posthog-node": "^5.11.0",