@plumbus/core 0.6.3 → 0.6.5

package/instructions/testing.md

@@ -15,15 +15,19 @@ import { runCapability, simulateFlow, mockAI, createTestContext } from "@plumbus
 Execute a capability in an isolated test environment:
 
 ```ts
-const result = await runCapability(getUser, {
-  input: { userId: "usr_123" },
-  auth: { userId: "admin_1", roles: ["admin"], scopes: [], provider: "test" },
-  data: {
-    User: [{ id: "usr_123", name: "Alice", email: "alice@test.com" }],
+const result = await runCapability(
+  getUser,
+  { userId: "usr_123" },
+  {
+    auth: { userId: "admin_1", roles: ["admin"], scopes: [], provider: "test" },
+    data: {
+      User: [{ id: "usr_123", name: "Alice", email: "alice@test.com" }],
+    },
   },
-});
+);
 
-expect(result.name).toBe("Alice");
+expect(result.success).toBe(true);
+expect(result.data?.name).toBe("Alice");
 ```
 
 ### Paginated list capabilities
@@ -37,8 +41,10 @@ When testing `kind: 'query'` list endpoints that paginate via `findMany` + `coun
 ```ts
 const page1 = await runCapability(listStaff, { page: 1, limit: 2 }, { ctx });
 const page2 = await runCapability(listStaff, { page: 2, limit: 2 }, { ctx });
-expect(page1.items).not.toEqual(page2.items);
-expect(page1.total).toBeGreaterThan(page1.limit);
+expect(page1.success && page1.data).toBeTruthy();
+expect(page2.success && page2.data).toBeTruthy();
+expect(page1.data.items).not.toEqual(page2.data.items);
+expect(page1.data.total).toBeGreaterThan(page1.data.limit);
 ```
 
 ### `simulateFlow`
@@ -46,16 +52,21 @@ expect(page1.total).toBeGreaterThan(page1.limit);
 Simulate flow execution and inspect step history:
 
 ```ts
-const execution = await simulateFlow("refundApproval", {
-  input: { refundId: "rf_1", amount: 50 },
-  events: {
-    "refund.approved": { refundId: "rf_1", approvedBy: "mgr_1" },
+import { refundApproval } from "../refundApproval/flow.js";
+
+const execution = await simulateFlow(
+  refundApproval,
+  { refundId: "rf_1", amount: 50 },
+  {
+    capabilityResults: {
+      "billing.validateRefund": { valid: true },
+    },
   },
-});
+);
 
 expect(execution.status).toBe("completed");
-expect(execution.steps).toHaveLength(4);
-expect(execution.steps[0].name).toBe("validateRefund");
+expect(execution.history.length).toBeGreaterThan(0);
+expect(execution.history[0]?.stepName).toBe("validateRefund");
 ```
 
 ### `mockAI`
@@ -65,7 +76,7 @@ Mock AI provider responses:
 ```ts
 const ctx = createTestContext({
   ai: mockAI({
-    summarizeTicket: { summary: "Customer wants refund", priority: "high", sentiment: "negative" },
+    generate: { summary: "Customer wants refund", priority: "high", sentiment: "negative" },
   }),
 });
 
@@ -73,6 +84,8 @@ const result = await ctx.ai.generate({ prompt: "summarizeTicket", input: { ticke
 expect(result.priority).toBe("high");
 ```
 
+`mockAI` keys responses by **operation** (`generate`, `extract`, `classify`, `retrieve`), not by prompt name. All prompts share the configured response for each operation.
+
 ### `createTestContext`
 
 Build a test `ctx` with controllable mocks:
@@ -101,21 +114,21 @@ const execution = await simulateFlow(myFlow, input, {
 ## Security Test Patterns
 
 ```ts
-// Assert unauthorized access is rejected
-await expect(
-  runCapability("deleteUser", {
-    input: { userId: "usr_1" },
-    auth: { roles: ["viewer"], scopes: [], provider: "test" },
-  })
-).rejects.toMatchObject({ code: "forbidden" });
-
-// Assert cross-tenant access is blocked
-await expect(
-  runCapability("getUser", {
-    input: { userId: "usr_1" },
-    auth: { tenantId: "other_tenant", roles: ["admin"], scopes: [], provider: "test" },
-  })
-).rejects.toMatchObject({ code: "forbidden" });
+import { assertCapabilityDenied } from "@plumbus/core/testing";
+
+// Assert unauthorized access is rejected (returns { success: false }, does not throw)
+const denied = await runCapability(
+  deleteUser,
+  { userId: "usr_1" },
+  { auth: { roles: ["viewer"], scopes: [], provider: "test" } },
+);
+expect(denied.success).toBe(false);
+expect(denied.error?.code).toBe("forbidden");
+
+// Or use the helper
+await assertCapabilityDenied(deleteUser, { userId: "usr_1" }, {
+  auth: { roles: ["viewer"], scopes: [], provider: "test" },
+});
 ```
 
 ## Governance Test Patterns

package/instructions/translations.md

@@ -30,7 +30,9 @@ export const commonTranslation = defineTranslation({
 
 - Place translation files in `app/translations/<name>.translation.ts` (classic layout), **or** use the locale-folder layout below
 - Each assembler exports one `defineTranslation()` result
-- All locales **must** have the same key set — mismatched keys throw at import time
+- All locales **must** have the same key set — mismatched keys fail at typecheck for literal catalogs and throw at import time otherwise
+- Prefer literal / `as const` catalogs so `tsc` catches drift. A locale typed as `Record<string, string>` skips compile-time key checks and still relies on import-time validation
+- When a non-default locale has an extra key, typecheck may error on the **default** locale (“missing key X”) while runtime errors on the **other** locale (“extra key X”) — both catch the same drift
 - Messages use ICU MessageFormat: `{name}` for interpolation, `{count, plural, ...}` for plurals, `{gender, select, ...}` for select
 - The `name` field is the namespace: keys resolve as `<namespace>.<key>` (e.g., `common.nav.overview`)
 
@@ -105,4 +107,21 @@ function Nav() {
 
 ## Translation Sync
 
-`defineTranslation()` validates key consistency at import time. If locale "he" is missing keys that "en" has, the app throws immediately. This ensures tests and CI catch translation drift.
+`defineTranslation()` enforces key consistency at typecheck for literal / `as const` catalogs, and again at import time. If locale "he" is missing keys that "en" has, `tsc` fails for typed catalogs and the app throws immediately otherwise. This ensures tests and CI catch translation drift.
+
+### Dynamic locales
+
+```ts
+const he: Record<string, string> = loadFromCms("he"); // no compile-time key parity
+
+defineTranslation({
+  name: "common",
+  defaultLocale: "en",
+  locales: ["en", "he"],
+  messages: {
+    en: { greeting: "Hello", farewell: "Bye" },
+    he,
+  },
+});
+// Runtime still throws if `he` is missing/extra keys relative to `en`.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,8 @@
   },
   "files": [
     "dist",
-    "instructions"
+    "instructions",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "plumbus",
@@ -95,8 +96,8 @@
     "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
     "@plumbus/api": "0.1.2",
-    "@plumbus/mcp": "0.5.1",
-    "@plumbus/voice": "0.3.0"
+    "@plumbus/voice": "0.3.0",
+    "@plumbus/mcp": "0.5.1"
   },
   "scripts": {
     "build": "tsc -b",
@@ -109,6 +110,6 @@
     "lint": "biome lint ./src",
     "format": "biome format --write ./src",
     "format:check": "biome format ./src",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && node ./scripts/check-define-translation-types.mjs"
   }
 }