@acmekit/acmekit 2.13.86 → 2.13.87

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

@@ -450,29 +450,23 @@ describe("MyProvider", () => {
 
 ---
 
-## Asserting Domain Events (module mode)
+## Asserting Domain Events
 
-```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
+`MockEventBusService` accumulates emitted events — use `.getEmittedEvents()` directly, no spy needed.
 
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
+```typescript
+import { Modules } from "@acmekit/framework/utils"
 
 it("should emit post.created event", async () => {
   await service.createPosts([{ title: "Event Test" }])
 
-  const events = eventBusSpy.mock.calls[0][0]
+  // Access events directly from the mock event bus — no spy needed
+  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "post.created",
+        name: "post.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -480,6 +474,8 @@ it("should emit post.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## What to Test

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

@@ -520,29 +520,18 @@ expect(response.data).toEqual({
 
 ## Asserting Domain Events
 
-Both runners inject `MockEventBusService` under `Modules.EVENT_BUS` in module mode. Spy on the **prototype**, not an instance.
+`MockEventBusService` accumulates all emitted events. Use `.getEmittedEvents()` — no spy needed.
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
-
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
-
 it("should emit post.created event", async () => {
   await service.createPosts([{ title: "Event Test" }])
 
-  const events = eventBusSpy.mock.calls[0][0]
+  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "post.created",
+        name: "post.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -550,6 +539,8 @@ it("should emit post.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## Waiting for Subscribers
@@ -904,6 +895,42 @@ await expect(provider.process(badInput)).rejects.toThrow("validation")
 
 ---
 
+## Auto-Injected Infrastructure Mocks
+
+The test runner automatically injects mock implementations for infrastructure modules in plugin and module modes. You do NOT need to manually inject these:
+
+| Module | Mock class | Behavior |
+|---|---|---|
+| `Modules.EVENT_BUS` | `MockEventBusService` | Accumulates events — call `.getEmittedEvents()` to inspect |
+| `Modules.LOCKING` | `MockLockingService` | In-memory locking — `execute()` runs job immediately, acquire/release tracked |
+| `Modules.SECRETS` | `MockSecretsService` | In-memory store — pre-populate with `.setSecret(id, value)` |
+
+Override any mock via `injectedDependencies` if needed — user overrides take precedence.
+
+### Asserting emitted events (no spy needed)
+
+```typescript
+const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+
+await createPostWorkflow(getContainer()).run({ input: { title: "Test" } })
+
+// Inspect emitted events directly — no jest.spyOn needed
+const events = eventBus.getEmittedEvents()
+const postEvent = events.find((e: any) => e.name === "post.created")
+expect(postEvent).toBeDefined()
+expect(postEvent.data).toEqual(expect.objectContaining({ id: expect.any(String) }))
+```
+
+> Event objects have `{ name, data, metadata?, options? }`. The property is `name`, NOT `eventName` — `emitEventStep` maps `eventName` to `name` internally.
+
+---
+
+## Client Routes Require API Key
+
+Routes under `/client/*` use `AcmeKitTypedRequest` (non-authenticated), but they are NOT fully public. AcmeKit middleware enforces a client API key header on all `/client/*` routes. "Public" means "no user authentication" — a client API key is still required.
+
+---
+
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
@@ -1068,4 +1095,15 @@ const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
 const result = await provider.process(bad)
 expect(result.success).toBe(false)  // ❌ actually throws
 // RIGHT — read implementation first to check if it throws or returns
+
+// WRONG — using jest.spyOn to inspect emitted events
+jest.spyOn(MockEventBusService.prototype, "emit")  // ❌ fragile, complex extraction
+// RIGHT — use built-in event accumulation
+const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+const events = eventBus.getEmittedEvents()
+
+// WRONG — checking event.eventName (emitEventStep maps eventName → name internally)
+expect(event.eventName).toBe("post.created")  // ❌ property doesn't exist
+// RIGHT
+expect(event.name).toBe("post.created")
 ```

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

@@ -471,31 +471,22 @@ describe("MyProvider", () => {
 
 ## Asserting Domain Events (container-only mode)
 
-Plugin mode (without HTTP) injects `MockEventBusService`. Spy on the **prototype**, not an instance.
+`MockEventBusService` accumulates emitted events — use `.getEmittedEvents()` directly, no spy needed.
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
-
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
+import { Modules } from "@acmekit/framework/utils"
 
 it("should emit greeting.created event", async () => {
   const service: any = container.resolve(GREETING_MODULE)
   await service.createGreetings([{ message: "Event Test" }])
 
-  // MockEventBusService.emit receives an ARRAY of events
-  const events = eventBusSpy.mock.calls[0][0]
+  // Access events directly from the mock event bus — no spy needed
+  const eventBus = container.resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "greeting.created",
+        name: "greeting.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -503,6 +494,8 @@ it("should emit greeting.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## What to Test
@@ -538,8 +531,8 @@ it("should emit greeting.created event", async () => {
 - Auth: 401 without JWT, 400 without client API key
 
 **Events (container mode):**
-- Spy on `MockEventBusService.prototype.emit` (prototype, not instance)
-- Access events via `eventBusSpy.mock.calls[0][0]` (array of event objects)
+- Use `container.resolve(Modules.EVENT_BUS).getEmittedEvents()` — no spy needed
+- Event objects have `{ name, data }` — property is `name`, NOT `eventName`
 
 ---
 
@@ -576,8 +569,8 @@ it("should emit greeting.created event", async () => {
 - Use realistic test data ("Launch Announcement", "Quarterly Report") not "test", "foo"
 - Pass body directly: `api.post(url, body, headers)` — NOT `{ body: {...} }`
 - Runners handle DB setup/teardown — no manual cleanup needed
-- Spy on `MockEventBusService.prototype` — not an instance
-- `jest.restoreAllMocks()` in `afterEach` when spying
+- Use `eventBus.getEmittedEvents()` for event assertions — no spy ceremony
+- Event property is `name`, NOT `eventName` (`emitEventStep` maps internally)
 - 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

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

@@ -492,34 +492,27 @@ integrationTestRunner({
 
 ## Asserting Domain Events
 
-Plugin mode (without HTTP) injects `MockEventBusService`. Spy on the **prototype**, not an instance.
+`MockEventBusService` accumulates all emitted events. Use `.getEmittedEvents()` — no spy needed.
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
+it("should emit greeting.created event", async () => {
+  const service = container.resolve(GREETING_MODULE)
+  await service.createGreetings([{ message: "Hello" }])
 
-it("should capture events", async () => {
-  const spy = jest.spyOn(MockEventBusService.prototype, "emit")
   const eventBus = container.resolve(Modules.EVENT_BUS)
-
-  await eventBus.emit([
-    { name: "greeting.created", data: { id: "g1", message: "Hello" } },
-  ])
-
-  expect(spy).toHaveBeenCalledTimes(1)
-  expect(spy.mock.calls[0][0]).toEqual(
+  const events = eventBus.getEmittedEvents()
+  expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "greeting.created",
-        data: expect.objectContaining({ id: "g1" }),
+        name: "greeting.created",  // NOTE: property is "name", NOT "eventName"
+        data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
   )
-
-  spy.mockRestore()
 })
 ```
 
-**Note:** MockEventBusService `emit` takes an **array** of events. Real event bus `emit` takes a single `{ name, data }` object.
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
 
 ---
 
@@ -765,7 +758,9 @@ integrationTestRunner({
 
 ## Configuring Providers in Plugin Tests
 
-Use `pluginModuleOptions` to pass per-module options (e.g., provider configuration) keyed by module name:
+Providers CANNOT be mocked with `jest.mock({ virtual: true })`. The module loader uses `require.resolve()` which bypasses jest. Providers must be **real files on disk** exporting `ModuleProvider()`.
+
+Use `pluginModuleOptions` to register providers keyed by module name. Provider `resolve` paths must be **absolute** (the loader resolves from `modules-sdk` dist, not your test file):
 
 ```typescript
 integrationTestRunner({
@@ -775,8 +770,8 @@ integrationTestRunner({
     tron: {
       providers: [
         {
-          resolve: "./src/providers/energy/own-pool",
-          id: "own-pool",
+          resolve: process.cwd() + "/integration-tests/helpers/mock-energy-provider",
+          id: "mock-energy",
           options: { apiKey: "test-key" },
         },
       ],
@@ -786,10 +781,108 @@ integrationTestRunner({
 })
 ```
 
+The helper file must be a real module:
+
+```typescript
+// integration-tests/helpers/mock-energy-provider.ts
+import { ModuleProvider } from "@acmekit/framework/utils"
+
+class MockEnergyService {
+  static identifier = "mock-energy"
+  // implement provider interface methods
+}
+
+export default ModuleProvider("tron", { services: [MockEnergyService] })
+```
+
 `pluginModuleOptions` is merged into the discovered module config AFTER `pluginOptions`, so module-specific options override plugin-level ones.
 
 ---
 
+## Auto-Injected Infrastructure Mocks
+
+The test runner automatically injects mock implementations for infrastructure modules in plugin and module modes. You do NOT need to manually inject these:
+
+| Module | Mock class | Behavior |
+|---|---|---|
+| `Modules.EVENT_BUS` | `MockEventBusService` | Accumulates events — call `.getEmittedEvents()` to inspect |
+| `Modules.LOCKING` | `MockLockingService` | In-memory locking — `execute()` runs job immediately, acquire/release tracked |
+| `Modules.SECRETS` | `MockSecretsService` | In-memory store — pre-populate with `.setSecret(id, value)` |
+
+Override any mock via `injectedDependencies` if needed — user overrides take precedence.
+
+### Asserting emitted events (no spy needed)
+
+```typescript
+// Resolve the mock event bus from the container
+const eventBus = container.resolve(Modules.EVENT_BUS)
+
+// Run your workflow/operation that emits events
+await createGreetingsWorkflow(container).run({ input: { greetings: [{ message: "Hi" }] } })
+
+// Inspect emitted events directly — no jest.spyOn needed
+const events = eventBus.getEmittedEvents()
+const greetingEvent = events.find((e: any) => e.name === "greeting.created")
+expect(greetingEvent).toBeDefined()
+expect(greetingEvent.data).toEqual(expect.objectContaining({ id: expect.any(String) }))
+```
+
+> Event objects have `{ name, data, metadata?, options? }`. The property is `name`, NOT `eventName` — `emitEventStep` maps `eventName` to `name` internally.
+
+### Pre-populating secrets for tests
+
+```typescript
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  testSuite: ({ container }) => {
+    beforeEach(() => {
+      const secrets = container.resolve(Modules.SECRETS)
+      secrets.setSecret("prod/wallet", { address: "0xtest123" })
+    })
+
+    it("resolves wallet address from secrets", async () => {
+      const addr = await container.resolve(Modules.SECRETS).getKey("prod/wallet", "address")
+      expect(addr).toBe("0xtest123")
+    })
+  },
+})
+```
+
+---
+
+## injectedDependencies vs pluginModuleOptions
+
+| | `injectedDependencies` | `pluginModuleOptions` |
+|---|---|---|
+| **Injects into** | Root container | Per-module config |
+| **Use for** | Infrastructure mocks (locking, secrets, custom services) | Provider registration, module-specific config |
+| **Shape** | `{ [Modules.X]: mockInstance }` | `{ moduleName: { providers: [...], options } }` |
+| **Path resolution** | N/A | Must be **absolute** (`process.cwd() + "/path"`) |
+
+---
+
+## Client Routes Require API Key
+
+Routes under `/client/*` use `AcmeKitTypedRequest` (non-authenticated), but they are NOT fully public. AcmeKit middleware enforces a client API key header on all `/client/*` routes.
+
+```typescript
+// WRONG — 401 "Client API key required"
+const response = await api.get("/client/plugin/greetings")  // ❌
+
+// RIGHT — create client API key and pass header
+const apiKey = await apiKeyModule.createApiKeys({
+  title: "Test Client Key",
+  type: ApiKeyType.CLIENT,
+  created_by: "test",
+})
+const response = await api.get("/client/plugin/greetings", {
+  headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
+})
+```
+
+---
+
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
@@ -915,4 +1008,26 @@ const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
 const result = await provider.process(bad)
 expect(result.success).toBe(false)  // ❌ actually throws
 // RIGHT — read implementation first to check if it throws or returns
+
+// WRONG — jest virtual mock for providers (require.resolve bypasses jest)
+jest.mock("../../src/providers/mock-provider", () => ({ ... }), { virtual: true })  // ❌
+// RIGHT — create a real file and use absolute path
+// integration-tests/helpers/mock-provider.ts (real file with ModuleProvider export)
+pluginModuleOptions: { mod: { providers: [{ resolve: process.cwd() + "/integration-tests/helpers/mock-provider" }] } }
+
+// WRONG — relative provider resolve path (resolved from modules-sdk dist, not test file)
+{ resolve: "../../src/providers/my-provider" }  // ❌
+// RIGHT
+{ resolve: process.cwd() + "/src/providers/my-provider" }
+
+// WRONG — using jest.spyOn to inspect emitted events
+jest.spyOn(MockEventBusService.prototype, "emit")  // ❌ fragile, complex extraction
+// RIGHT — use built-in event accumulation
+const eventBus = container.resolve(Modules.EVENT_BUS)
+const events = eventBus.getEmittedEvents()
+
+// WRONG — checking event.eventName (emitEventStep maps eventName → name internally)
+expect(event.eventName).toBe("greeting.created")  // ❌ property doesn't exist
+// RIGHT
+expect(event.name).toBe("greeting.created")
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acmekit/acmekit",
-  "version": "2.13.86",
+  "version": "2.13.87",
   "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.86"
+    "@acmekit/framework": "2.13.87"
   },
   "dependencies": {
-    "@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",
+    "@acmekit/admin-bundler": "2.13.87",
+    "@acmekit/analytics": "2.13.87",
+    "@acmekit/analytics-local": "2.13.87",
+    "@acmekit/analytics-posthog": "2.13.87",
+    "@acmekit/api-key": "2.13.87",
+    "@acmekit/auth": "2.13.87",
+    "@acmekit/auth-emailpass": "2.13.87",
+    "@acmekit/auth-github": "2.13.87",
+    "@acmekit/auth-google": "2.13.87",
+    "@acmekit/cache-inmemory": "2.13.87",
+    "@acmekit/cache-redis": "2.13.87",
+    "@acmekit/caching": "2.13.87",
+    "@acmekit/caching-redis": "2.13.87",
+    "@acmekit/core-flows": "2.13.87",
+    "@acmekit/event-bus-local": "2.13.87",
+    "@acmekit/event-bus-redis": "2.13.87",
+    "@acmekit/file": "2.13.87",
+    "@acmekit/file-local": "2.13.87",
+    "@acmekit/file-s3": "2.13.87",
+    "@acmekit/index": "2.13.87",
+    "@acmekit/link-modules": "2.13.87",
+    "@acmekit/locking": "2.13.87",
+    "@acmekit/locking-postgres": "2.13.87",
+    "@acmekit/locking-redis": "2.13.87",
+    "@acmekit/notification": "2.13.87",
+    "@acmekit/notification-local": "2.13.87",
+    "@acmekit/notification-sendgrid": "2.13.87",
+    "@acmekit/rbac": "2.13.87",
+    "@acmekit/secrets-aws": "2.13.87",
+    "@acmekit/secrets-local": "2.13.87",
+    "@acmekit/settings": "2.13.87",
+    "@acmekit/telemetry": "2.13.87",
+    "@acmekit/translation": "2.13.87",
+    "@acmekit/user": "2.13.87",
+    "@acmekit/workflow-engine-inmemory": "2.13.87",
+    "@acmekit/workflow-engine-redis": "2.13.87",
     "@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.86",
+    "@acmekit/framework": "2.13.87",
     "@jimsheen/yalc": "^1.2.2",
     "@swc/core": "^1.7.28",
     "posthog-node": "^5.11.0",