@acmekit/acmekit 2.13.89 → 2.13.91

package/dist/templates/app/.claude/rules/admin-patterns.md

@@ -867,7 +867,17 @@ import { sdk } from "../../../../lib/sdk"
 type Currency = { code: string; name: string }
 const columnHelper = createDataTableColumnHelper<Currency>()
 
+// Page component — renders RouteFocusModal, delegates form to child
 const AddCurrenciesPage = () => {
+  return (
+    <RouteFocusModal>
+      <AddCurrenciesForm />
+    </RouteFocusModal>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteFocusModal)
+const AddCurrenciesForm = () => {
   const queryClient = useQueryClient()
   const { handleSuccess } = useRouteModal()
 
@@ -924,37 +934,35 @@ const AddCurrenciesPage = () => {
   })
 
   return (
-    <RouteFocusModal>
-      <RouteFocusModal.Form form={form}>
-        <KeyboundForm onSubmit={handleSubmit} className="flex h-full flex-col overflow-hidden">
-          <RouteFocusModal.Header>
-            <div className="flex flex-1 items-center justify-between">
-              {form.formState.errors.currencies && (
-                <Hint variant="error">{form.formState.errors.currencies.message}</Hint>
-              )}
-            </div>
-          </RouteFocusModal.Header>
-          <RouteFocusModal.Body className="flex flex-1 flex-col overflow-hidden">
-            <DataTable instance={table}>
-              <DataTable.Table emptyState={{
-                empty: { heading: "No currencies available" },
-              }} />
-              <DataTable.Pagination />
-            </DataTable>
-          </RouteFocusModal.Body>
-          <RouteFocusModal.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <RouteFocusModal.Close asChild>
-                <Button size="small" variant="secondary">Cancel</Button>
-              </RouteFocusModal.Close>
-              <Button size="small" type="submit" isLoading={isPending}>
-                Save
-              </Button>
-            </div>
-          </RouteFocusModal.Footer>
-        </KeyboundForm>
-      </RouteFocusModal.Form>
-    </RouteFocusModal>
+    <RouteFocusModal.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex h-full flex-col overflow-hidden">
+        <RouteFocusModal.Header>
+          <div className="flex flex-1 items-center justify-between">
+            {form.formState.errors.currencies && (
+              <Hint variant="error">{form.formState.errors.currencies.message}</Hint>
+            )}
+          </div>
+        </RouteFocusModal.Header>
+        <RouteFocusModal.Body className="flex flex-1 flex-col overflow-hidden">
+          <DataTable instance={table}>
+            <DataTable.Table emptyState={{
+              empty: { heading: "No currencies available" },
+            }} />
+            <DataTable.Pagination />
+          </DataTable>
+        </RouteFocusModal.Body>
+        <RouteFocusModal.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteFocusModal.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteFocusModal.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Save
+            </Button>
+          </div>
+        </RouteFocusModal.Footer>
+      </KeyboundForm>
+    </RouteFocusModal.Form>
   )
 }
 

package/dist/templates/app/.claude/rules/admin-ui.md

@@ -422,6 +422,34 @@ const SettingsPage = () => {
 }
 ```
 
+### Never Install react-hook-form, @hookform/resolvers, or zod Directly
+
+These packages are **provided by AcmeKit** at specific pinned versions. Installing your own version causes version conflicts:
+
+- `@hookform/resolvers@5.x` requires `zod/v4/core` (Zod v4) — AcmeKit ships Zod v3 → **build fails** with `Could not resolve "zod/v4/core"`
+- `react-hook-form` dual instances → `useFormContext()` returns `null` → form fields crash
+- Bare `zod` import → **build fails** in plugins with `Could not resolve "zod"`
+
+**For plugins**: `react-hook-form` and `@hookform/resolvers` go in `peerDependencies` + `devDependencies` only (never `dependencies`). Match the host app's versions.
+
+**For apps**: Do not add these packages at all — they come from `@acmekit/ui`.
+
+**Imports**:
+- Admin UI: `import * as zod from "@acmekit/deps/zod"` — never bare `"zod"`
+- Backend: `import { z } from "@acmekit/framework/zod"` — never bare `"zod"`
+- `useForm` from `react-hook-form` and `zodResolver` from `@hookform/resolvers/zod` — these are provided by the host
+
+### Vite "Outdated Optimize Dep" 504 Errors
+
+After changing plugin dependencies, Vite's pre-bundled dependency cache becomes stale. The browser shows `504 (Outdated Optimize Dep)` for multiple modules.
+
+**Fix**: Stop the dev server, delete `.vite/deps/` in the host app's `node_modules/`, and restart:
+
+```bash
+rm -rf node_modules/.vite/deps
+# restart dev server
+```
+
 ---
 
 ## Key Rules

package/dist/templates/app/.claude/rules/api-routes.md

@@ -42,7 +42,7 @@ Co-locate validation, query config, response schemas, rate limiting, and RBAC po
 When extending generated CRUD routes, keep the existing `query-config.ts` / `helpers.ts` structure and only adjust fields, filters, workflow calls, or refetch logic.
 
 ```typescript
-import { z } from "zod"
+import { z } from "@acmekit/framework/zod"
 import {
   defineRouteConfig,
   AuthenticatedAcmeKitTypedRequest,
@@ -532,8 +532,9 @@ createProductsWorkflow.hooks.productsCreated(
 
 ## Zod Import Note
 
-- In route files (`defineRouteConfig`): `import { z } from "zod"` works
-- In `middlewares.ts` (`additionalDataValidator`): use `import { z } from "@acmekit/framework/zod"`
+- **Always** use `import { z } from "@acmekit/framework/zod"` — never bare `"zod"`
+- Bare `"zod"` may resolve in apps but **fails in plugins** (zod is not a direct dependency)
+- This applies to both route files and `middlewares.ts`
 
 ## Common Imports
 
@@ -546,8 +547,7 @@ import {
   defineMiddlewares,
   AcmeKitNextFunction,
 } from "@acmekit/framework/http"
-import { z } from "zod"
-import { z as frameworkZod } from "@acmekit/framework/zod"  // for middlewares.ts
+import { z } from "@acmekit/framework/zod"
 import { ContainerRegistrationKeys, AcmeKitError } from "@acmekit/framework/utils"
 ```
 
@@ -737,11 +737,10 @@ export const POST = async (req, res) => {
 // RIGHT — use :param format
 { matcher: "/custom/:id", middlewares: [...] }  // ✅
 
-// WRONG — using bare zod in middlewares.ts
-import { z } from "zod"  // ❌ in middlewares.ts
-additionalDataValidator: { brand: z.string() }
+// WRONG — bare "zod" import (fails in plugins, not a direct dependency)
+import { z } from "zod"  // ❌ never use bare zod
 
-// RIGHT — use framework zod in middlewares.ts
+// RIGHT — always use framework re-export
 import { z } from "@acmekit/framework/zod"  // ✅
 
 // WRONG — no .strict() on body schema (allows extra fields through)
@@ -772,4 +771,26 @@ const { enabled, ...filters } = req.validatedQuery  // ❌ crashes if request ha
 
 // RIGHT — always provide fallback when destructuring validatedQuery
 const { enabled, ...filters } = req.validatedQuery ?? {}  // ✅ safe when no query params
+
+// WRONG — seeding/syncing data inside a route handler (runs on every request)
+export const GET = async (req, res) => {
+  const service = req.scope.resolve(MY_MODULE)
+  await service.syncProviders()  // ❌ data mutation on every GET — slow, side-effectful
+  const data = await query.graph({ entity: "my_entity" })
+  res.json({ items: data })
+}
+
+// RIGHT — routes are pure query/mutation handlers, no seeding or syncing
+// Seed data via: createProvidersLoader onRegistered, onPluginStart, or scripts
+export const GET = async (req, res) => {
+  const data = await query.graph({ entity: "my_entity" })
+  res.json({ items: data })  // ✅ just reads data
+}
+
+// WRONG — importing service class directly in route file for type
+import type MyModuleService from "../../../modules/my/service"  // ❌ tight coupling
+const svc = req.scope.resolve<MyModuleService>(MY_MODULE)
+
+// RIGHT — resolve via module constant, type-cast loosely if needed
+const svc: any = req.scope.resolve(MY_MODULE)  // ✅
 ```

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

@@ -97,7 +97,7 @@ export const BLOG_MODULE = "blog"
 export default Module(BLOG_MODULE, { service: BlogModuleService })
 ```
 
-The generator auto-registers modules in `acmekit-config.ts`. Verify registration after generation and preserve the generated constant naming.
+The generator auto-registers modules in `acmekit-config.ts`. Verify registration after generation.
 
 ## Constructor Pattern
 
@@ -192,7 +192,7 @@ export default class MyModuleService {
 
 **When to use loaders:** Register external connections at startup; validate required options (throw on missing to prevent startup). Loaders are idempotent — check `container.hasRegistration("key")` before re-registering.
 
-**Don't use loaders for:** Scheduled tasks → use jobs. Event-triggered logic → use subscribers.
+**Don't use loaders for:** Scheduled tasks → use jobs. Event-triggered logic → use subscribers. Database mutations (INSERT/UPDATE/DELETE) → use scripts, subscribers, or seed data (exception: `onRegistered` in `createProvidersLoader` is designed for DB seeding via service methods). Never resolve `PG_CONNECTION` for raw SQL in loaders — use service methods instead.
 
 ## Module Options Validation
 
@@ -262,6 +262,73 @@ export default Module(RELAYER_MODULE, {
 })
 ```
 
+### createProvidersLoader — Full API
+
+`createProvidersLoader` accepts a `ProvidersConfig` object with these options:
+
+| Option | Required | Default | Purpose |
+|--------|----------|---------|---------|
+| `prefix` | Yes | — | Container registration key prefix (e.g., `"pp_"`, `"cr_"`) |
+| `identifiersKey` | Yes | — | Key for tracking registered provider IDs |
+| `moduleName` | No | `"module"` | Label for log/error messages |
+| `keyFormat` | No | `"prefixId"` | `"prefixId"` → key=`{prefix}{id}`, or `"prefixIdentifierId"` → key=`{prefix}{identifier}_{id}` |
+| `defaults` | No | `[]` | Built-in providers shipped with the module (see below) |
+| `defaultProviderKey` | No | — | Container key to register the elected default provider ID |
+| `requireDefault` | No | `false` | Throw at startup if no default provider is found |
+| `onRegistered` | No | — | Async hook called after all providers are registered |
+
+**`defaults`** — each entry is a `DefaultProviderConfig`:
+
+```typescript
+{
+  service: ProviderClass,      // must have static `identifier`
+  id: string,                  // registration ID
+  options?: Record | ((moduleOptions) => Record),  // static or derived from module options
+  condition?: (moduleOptions) => boolean,           // skip this default if returns false
+}
+```
+
+**`onRegistered`** — receives `{ container, providers, registeredDefaults }`:
+
+```typescript
+onRegistered: async ({ container, providers, registeredDefaults }) => {
+  // container: module-scoped AcmeKitContainer (module's own service is resolvable here)
+  // providers: user-configured ModuleProvider[] from config
+  // registeredDefaults: Array<{ id, options }> — only defaults that passed condition
+}
+```
+
+**Example with defaults and onRegistered** (from core modules):
+
+```typescript
+createProvidersLoader({
+  prefix: PAYMENT_PROVIDER_PREFIX,
+  identifiersKey: PAYMENT_PROVIDER_IDENTIFIER_KEY,
+  moduleName: PAYMENT_MODULE,
+  defaults: [
+    {
+      service: SystemProvider,
+      id: "system",
+      condition: (opts) => opts.enableSystemProvider !== false,
+    },
+  ],
+  onRegistered: async ({ container, registeredDefaults }) => {
+    // Sync DB rows for registered providers via service methods
+    const service: any = container.resolve(PAYMENT_MODULE)
+    for (const provider of registeredDefaults) {
+      const existing = await service.listPaymentProviders({ id: [provider.id] })
+      if (!existing.length) {
+        await service.createPaymentProviders([
+          { id: provider.id, is_enabled: true },
+        ])
+      }
+    }
+  },
+})
+```
+
+**Important**: Even inside `onRegistered`, always use service methods for DB mutations — never raw SQL via `PG_CONNECTION`.
+
 ### Service (resolving providers)
 
 Use the leading `TProvider` generic to get a typed `this.providers` registry.
@@ -767,4 +834,54 @@ AcmeKitService({ providers: { prefix: "cr_", identifiersKey: "chain_relayer_prov
 
 // RIGHT — define constants once in constants.ts, import everywhere
 import { CHAIN_RELAYER_PROVIDER_PREFIX, CHAIN_RELAYER_IDENTIFIER_KEY } from "./constants"
+
+// WRONG — using raw SQL / PG_CONNECTION for data mutations
+const pgConnection = container.resolve(ContainerRegistrationKeys.PG_CONNECTION)
+await pgConnection.raw(
+  `INSERT INTO payment_provider (id) VALUES (?)`,  // ❌ bypasses ORM, service layer, events
+  [id]
+)
+
+// RIGHT — use the module's service methods for all data mutations
+const service = container.resolve(PAYMENT_MODULE)
+await service.createPaymentProviders([{ id: "pp_system", is_enabled: true }])  // ✅
+
+// WRONG — using raw SQL in onRegistered to seed provider rows
+onRegistered: async ({ container, registeredDefaults }) => {
+  const pg = container.resolve(ContainerRegistrationKeys.PG_CONNECTION)
+  await pg.raw(`INSERT INTO ...`, [id])  // ❌ bypasses ORM
+}
+
+// RIGHT — use service methods in onRegistered
+onRegistered: async ({ container, registeredDefaults }) => {
+  const service: any = container.resolve(MY_MODULE)
+  for (const provider of registeredDefaults) {
+    const existing = await service.listMyProviders({ id: [provider.id] })
+    if (!existing.length) {
+      await service.createMyProviders([{ id: provider.id, is_enabled: true }])  // ✅
+    }
+  }
+}
+
+// WRONG — lazy-syncing / seeding data inside a GET route handler
+export const GET = async (req, res) => {
+  const service = req.scope.resolve(PAYMENT_MODULE)
+  await service.syncRegisteredProviders()  // ❌ runs on EVERY request
+  const { data } = await query.graph({ entity: "payment_provider" })
+  res.json({ items: data })
+}
+
+// RIGHT — seed data once at startup (onPluginStart) or via script, route just queries
+export const GET = async (req, res) => {
+  const { data } = await query.graph({ entity: "payment_provider" })
+  res.json({ items: data })  // ✅ pure query, no side effects
+}
+
+// WRONG — importing service class directly in route file
+import type PaymentModuleService from "../../../modules/payment/service"  // ❌
+const service = req.scope.resolve<PaymentModuleService>(PAYMENT_MODULE)
+
+// RIGHT — resolve with module constant, cast to interface if needed
+const service: any = req.scope.resolve(PAYMENT_MODULE)  // ✅
+// or use the generated interface type from @types if available
 ```

package/dist/templates/app/.claude/skills/build-feature/SKILL.md

@@ -497,6 +497,7 @@ src/admin/routes/<feature>/
 - Fields: `grid grid-cols-1 gap-4 md:grid-cols-2`
 - Footer: `<div className="flex items-center justify-end gap-x-2">`, submit `type="submit"`
 - All buttons `size="small"`, use `useRouteModal()` for `handleSuccess`
+- **IMPORTANT**: `useRouteModal()` must be in a **child component** rendered inside `<RouteFocusModal>` — split into page (renders modal) + form (calls hook)
 
 **Edit form** (`[id]/edit/page.tsx`):
 - `<RouteDrawer>` (auto-opens, navigates back on close)
@@ -505,6 +506,7 @@ src/admin/routes/<feature>/
 - Body fields: single column `flex flex-col gap-y-4` (drawer is narrow)
 - Footer: same as create
 - Loading guard wraps the `<KeyboundForm>`, not just body content
+- **IMPORTANT**: `useRouteModal()` must be in a **child component** rendered inside `<RouteDrawer>` — split into page (renders drawer) + form (calls hook)
 
 #### Multi-Entity Feature
 

package/dist/templates/app/CLAUDE.md

@@ -13,6 +13,7 @@ You are a senior AcmeKit framework developer. Build features using code generato
 - Use string literals for container keys — use `ContainerRegistrationKeys.*` and `Modules.*`
 - Call services directly for mutations in routes — use workflows
 - Put business logic in workflow steps — steps are thin wrappers; service methods own orchestration
+- Use raw SQL via `PG_CONNECTION` / `pgConnection.raw()` for data mutations — use service methods
 
 ### Ask First