create-m5kdev 0.34.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m5kdev",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "license": "GPL-3.0-only",
   "engines": {
     "node": ">=24"

package/templates/minimal-app/.cursor/rules/frontend-data-guide.mdc

@@ -88,6 +88,7 @@ Mutation input shapes are enforced by the router's inferred types — no
 
 - Invalidate intentionally with the matching `queryFilter()` after mutations.
 - Never call `queryClient.clear()` or invalidate everything.
+- Background Workflow completions: invalidate from a `ServerEventProvider` handler. The trigger mutation only returns `jobId`. See `.cursor/rules/server-event-emit.mdc`.
 
 ## Pending state
 

package/templates/minimal-app/.cursor/rules/server-event-emit.mdc

@@ -0,0 +1,41 @@
+---
+description: Emit Server events from background jobs, not from mutations that already return the entity
+globs: **/*.service.ts,**/*.jobs.ts,**/App.tsx,**/*ServerEventProvider.tsx
+alwaysApply: false
+---
+
+# Server event emit
+
+Emit through Auth (`userEmit`, `batchUserEmit`, `organizationEmit`, `emitServerEvent`) when work finishes **off the request** that started it. Typical case: a Workflow job. The UI will not get a completion payload, so SSE tells it to refetch or patch cache.
+
+The acting User already receives the mutation result. They do not need an SSE for that write.
+
+## Emit from
+
+- Workflow job `.handle` after the job creates or updates a resource
+- Other background work the User did not wait on (cron, inbound callback that persisted something)
+
+```typescript
+.handle(async (payload) => {
+  // ... job work ...
+  this.service.auth.userEmit({
+    userId: payload.userId,
+    resource: "workflow",
+    id: jobName,
+    change: "updated",
+    organizationId: null,
+  });
+});
+```
+
+Call Auth directly. Do not wrap `userEmit` in a private helper that only forwards.
+
+## Organization fan-out
+
+`organizationEmit` (or `emitServerEvent` with an Organization id) notifies **other Members**. Use it when a background job (or similar off-request work) creates or changes an org-scoped entity those Members must see. Skip it for tRPC writes that already return the entity, including publish.
+
+## Client
+
+Mount `ServerEventProvider` in the app shell. Register a handler that invalidates the matching `queryFilter()`. Reconnect has no replay: `onReconnect` should invalidate the same queries. Keep polling only as a fallback for in-progress status (queued → running) if you emit only when the job finishes.
+
+Starter: `DemoWorkflowService` `demo.ping` + `trpc.workflow.list`.

package/templates/minimal-app/AGENTS.md.tpl

@@ -25,6 +25,7 @@
 - Do not add service methods that merely call another service. Call the owning service directly unless the method adds a business rule, authorization, validation, orchestration, a transaction boundary, or meaningful domain translation.
 - Renaming a dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a service wrapper.
 - Do not create Drizzle migrations by hand. Use the scaffolded config and your project migration workflow later if you need generated migrations.
+- Server event: emit through Auth from Workflow job handlers (and similar background work) when the UI must refresh a change the triggering mutation did not return. See `.cursor/rules/server-event-emit.mdc`.
 
 ## Frontend Conventions
 

package/templates/minimal-app/CLAUDE.md.tpl

@@ -117,6 +117,7 @@ The framework's detailed conventions live in `.cursor/rules/*.mdc`. Cursor appli
 | `.cursor/rules/module-dto-guide.mdc` | `apps/server/src/modules/**/*.dto.ts` |
 | `.cursor/rules/module-repository-guide.mdc` | `apps/server/src/modules/**/*.repository.ts` |
 | `.cursor/rules/module-service-guide.mdc` | `apps/server/src/modules/**/*.service.ts` |
+| `.cursor/rules/server-event-emit.mdc` | `*.service.ts`, `*.jobs.ts`, webapp `App.tsx` / `*ServerEventProvider.tsx` |
 | `.cursor/rules/module-trpc-guide.mdc` | `apps/server/src/modules/**/*.trpc.ts` |
 | `.cursor/rules/module-grants-guide.mdc` | `apps/server/src/modules/**/*.grants.ts` |
 | `.cursor/rules/module-module-guide.mdc` | `apps/server/src/modules/**/*.module.ts` |

package/templates/minimal-app/README.md.tpl

@@ -76,7 +76,8 @@ pnpm landing:deploy
 ```
 
 `app:deploy` / `landing:deploy` read that app’s `.env.production` and forward
-every key as `fly deploy --build-secret`. A missing env file errors with a
+every key as `fly deploy --build-secret` via Kernel bins
+(`m5kdev-fly-deploy` / `m5kdev-fly-secrets`). A missing env file errors with a
 copy-the-example message. Product data lives on the `libsql_data` volume at
 `/app/data` (`DATABASE_URL=file:/app/data/local.db`). Redis is a runtime secret,
 not an image layer.

package/templates/minimal-app/apps/e2e/servers.ts.tpl

@@ -61,6 +61,9 @@ function serverEnv(profile: E2EProfile, expo: boolean): Record<string, string> {
     BETTER_AUTH_SECRET: "auth-e2e-local-secret-auth-e2e-local-secret",
     SYSTEM_NOTIFICATION_EMAIL: "ops@auth-e2e.local",
     NODE_ENV: "development",
+    // hermetic: shared/.env Turso credentials must not leak into drizzle-kit
+    TURSO_DATABASE_URL: "",
+    TURSO_AUTH_TOKEN: "",
     // hermetic: a real key in the invoking shell would flip email mode to
     // "send" and the stored-email assertions would find nothing
     RESEND_API_KEY: "",

package/templates/minimal-app/apps/e2e/tests/expo-helpers.ts.tpl

@@ -1,40 +1,8 @@
-import type { BackendTRPCRouter } from "@m5kdev/backend/types";
-import { transformer } from "@m5kdev/commons/utils/trpc";
 import type { Page } from "@playwright/test";
 import { expect } from "@playwright/test";
-import { createTRPCClient, httpBatchLink } from "@trpc/client";
-import { type Profile, profiles } from "./helpers";
+import { createTrpcClient } from "./helpers";
 
-type FetchInit = NonNullable<Parameters<typeof fetch>[1]>;
-
-async function cookieHeader(page: Page, profile: Profile) {
-  const cookies = await page.context().cookies(profiles[profile].serverUrl);
-  return cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
-}
-
-export async function createExpoTrpcClient(page: Page, profile: Profile) {
-  const cookie = await cookieHeader(page, profile);
-
-  return createTRPCClient<BackendTRPCRouter>({
-    links: [
-      httpBatchLink({
-        url: `${profiles[profile].serverUrl}/trpc`,
-        fetch(url, options) {
-          const headers = new Headers(options?.headers);
-          if (cookie) {
-            headers.set("cookie", cookie);
-          }
-          return fetch(url, {
-            ...options,
-            body: options?.body ? (options.body as FetchInit["body"]) : undefined,
-            headers,
-          });
-        },
-        transformer,
-      }),
-    ],
-  });
-}
+export const createExpoTrpcClient = createTrpcClient;
 
 export async function expoSignUp(page: Page, email: string, password: string) {
   await page.goto("/signup");

package/templates/minimal-app/apps/e2e/tests/expo-standard.spec.ts.tpl

@@ -11,6 +11,7 @@ import {
   clearEmails,
   createProvisionedClaimUser,
   emailUrl,
+  findMemberByEmail,
   getUserState,
   latestEmail,
   profiles,
@@ -37,15 +38,26 @@ async function expectAuthOk(response: Awaited<ReturnType<typeof authFetch>>) {
 }
 
 async function inviteOrganizationMember(page: Page, email: string, role: "member" | "admin") {
+  const trpc = await createExpoTrpcClient(page, profile);
+  return trpc.auth.inviteOrganizationMember.mutate({ email, role });
+}
+
+async function listOrganizationMembers(page: Page) {
+  const trpc = await createExpoTrpcClient(page, profile);
+  return trpc.auth.listOrganizationMembers.query();
+}
+
+async function expectBetterAuthInviteForbidden(page: Page, email: string) {
   const response = await authFetch(page, profile, "/api/auth/organization/invite-member", {
     method: "POST",
     body: {
       organizationId: enterpriseOrgId,
       email,
-      role,
+      role: "member",
     },
   });
-  await expectAuthOk(response);
+  expect(response.ok, `${response.status} ${response.statusText}: ${response.text}`).toBe(false);
+  expect(response.status).toBe(403);
 }
 
 test.beforeEach(async ({ request }) => {
@@ -151,12 +163,21 @@ test("organization invite email lets a new user join without creating a separate
   const invitee = `expo.member.${Date.now()}@auth-e2e.local`;
 
   await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
-  await inviteOrganizationMember(page, invitee, "member");
+  const invited = await inviteOrganizationMember(page, invitee, "member");
+  expect(invited.member.userId).toBeNull();
+  expect(invited.invitation.memberId).toBe(invited.member.id);
+  expect(invited.invitation.status).toBe("pending");
+
+  const listed = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(listed?.id).toBe(invited.member.id);
+  expect(listed?.userId).toBeNull();
+  expect(listed?.invitationId).toBe(invited.invitation.id);
 
   const invite = await latestEmail(request, profile, {
     to: invitee,
     templateId: "organization-invite",
   });
+  expect(emailUrl(invite)).toContain(`/organization/accept-invitation?id=${invited.invitation.id}`);
 
   await expoLogoutNative(page);
   await page.goto(emailUrl(invite));
@@ -168,7 +189,9 @@ test("organization invite email lets a new user join without creating a separate
   const state = await getUserState(request, profile, invitee);
   expect(state.user.emailVerified).toBe(true);
   expect(state.organizations.map((organization) => organization.id)).toEqual([enterpriseOrgId]);
+  expect(state.organizations[0]?.memberId).toBe(invited.member.id);
   expect(state.latestSession?.activeOrganizationId).toBe(enterpriseOrgId);
+  expect(state.latestSession?.activeOrganizationMemberId).toBe(invited.member.id);
 });
 
 test("organization invite lets an existing user join an additional org", async ({
@@ -184,12 +207,14 @@ test("organization invite lets an existing user join an additional org", async (
   expect(beforeInvite.organizations[0]?.id).not.toBe(enterpriseOrgId);
 
   await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
-  await inviteOrganizationMember(page, email, "member");
+  const invited = await inviteOrganizationMember(page, email, "member");
+  expect(invited.member.userId).toBeNull();
 
   const invite = await latestEmail(request, profile, {
     to: email,
     templateId: "organization-invite",
   });
+  expect(emailUrl(invite)).toContain("/organization/accept-invitation?id=");
 
   await expoLogoutNative(page);
   await expoLoginNative(page, email, password);
@@ -206,7 +231,156 @@ test("organization invite lets an existing user join an additional org", async (
   expect(afterInvite.organizations.map((organization) => organization.id)).toContain(
     enterpriseOrgId
   );
+  expect(
+    afterInvite.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId
+  ).toBe(invited.member.id);
   expect(afterInvite.latestSession?.activeOrganizationId).toBe(enterpriseOrgId);
+  expect(afterInvite.latestSession?.activeOrganizationMemberId).toBe(invited.member.id);
+});
+
+test("invited membership role change applies before accept", async ({ page, request }) => {
+  const invitee = `expo.invite-role.${Date.now()}@auth-e2e.local`;
+
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  const invited = await inviteOrganizationMember(page, invitee, "member");
+  expect(invited.member.role).toBe("member");
+  expect(invited.member.userId).toBeNull();
+
+  const trpc = await createExpoTrpcClient(page, profile);
+  const updated = await trpc.auth.updateMemberRole.mutate({
+    memberId: invited.member.id,
+    role: "admin",
+  });
+  expect(updated).toEqual({ id: invited.member.id, role: "admin" });
+
+  const afterRole = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(afterRole?.id).toBe(invited.member.id);
+  expect(afterRole?.role).toBe("admin");
+  expect(afterRole?.userId).toBeNull();
+  expect(afterRole?.invitationId).toBe(invited.invitation.id);
+
+  const invite = await latestEmail(request, profile, {
+    to: invitee,
+    templateId: "organization-invite",
+  });
+  await expoLogoutNative(page);
+  await page.goto(emailUrl(invite));
+  await expect(page).toHaveURL(/\/signup/);
+  await page.getByTestId("signup-password").fill("password1234");
+  await page.getByTestId("signup-submit").click();
+  await expect(page.getByTestId("session-email")).toContainText(invitee);
+
+  const state = await getUserState(request, profile, invitee);
+  expect(state.organizations).toEqual([
+    expect.objectContaining({
+      id: enterpriseOrgId,
+      memberId: invited.member.id,
+      role: "admin",
+    }),
+  ]);
+});
+
+test("invited membership can be resent, role-updated, canceled, and revived", async ({ page }) => {
+  const invitee = `expo.invite-manage.${Date.now()}@auth-e2e.local`;
+
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  const invited = await inviteOrganizationMember(page, invitee, "member");
+  const resent = await inviteOrganizationMember(page, invitee, "member");
+  expect(resent.member.id).toBe(invited.member.id);
+  expect(resent.invitation.id).toBe(invited.invitation.id);
+
+  const trpc = await createExpoTrpcClient(page, profile);
+  await trpc.auth.updateMemberRole.mutate({ memberId: invited.member.id, role: "admin" });
+  const afterRole = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(afterRole?.role).toBe("admin");
+  expect(afterRole?.userId).toBeNull();
+
+  await trpc.auth.cancelOrganizationInvitation.mutate({
+    invitationId: invited.invitation.id,
+  });
+  expect(findMemberByEmail(await listOrganizationMembers(page), invitee)).toBeUndefined();
+
+  const revived = await inviteOrganizationMember(page, invitee, "member");
+  expect(revived.member.id).toBe(invited.member.id);
+  expect(revived.member.userId).toBeNull();
+});
+
+test("live member invite is rejected; remove and leave drop the seat", async ({
+  page,
+  request,
+}) => {
+  const email = `expo.live-member.${Date.now()}@auth-e2e.local`;
+  const password = "password1234";
+
+  await createVerifiedExpoAccount(page, request, email, password);
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  const invited = await inviteOrganizationMember(page, email, "member");
+
+  const invite = await latestEmail(request, profile, {
+    to: email,
+    templateId: "organization-invite",
+  });
+  await expoLogoutNative(page);
+  await expoLoginNative(page, email, password);
+  await page.goto(emailUrl(invite));
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return (
+        state.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId ??
+        null
+      );
+    })
+    .toBe(invited.member.id);
+
+  await expoLogoutNative(page);
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  const adminTrpc = await createExpoTrpcClient(page, profile);
+  await expect(
+    adminTrpc.auth.inviteOrganizationMember.mutate({ email, role: "member" })
+  ).rejects.toThrow(/live membership already exists/i);
+
+  await adminTrpc.auth.removeOrganizationMember.mutate({ memberId: invited.member.id });
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.some((organization) => organization.id === enterpriseOrgId);
+    })
+    .toBe(false);
+
+  const revived = await inviteOrganizationMember(page, email, "member");
+  expect(revived.member.id).toBe(invited.member.id);
+
+  const reinvite = await latestEmail(request, profile, {
+    to: email,
+    templateId: "organization-invite",
+  });
+  await expoLogoutNative(page);
+  await expoLoginNative(page, email, password);
+  await page.goto(emailUrl(reinvite));
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return (
+        state.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId ??
+        null
+      );
+    })
+    .toBe(invited.member.id);
+
+  const memberTrpc = await createExpoTrpcClient(page, profile);
+  await memberTrpc.auth.leaveOrganization.mutate();
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.some((organization) => organization.id === enterpriseOrgId);
+    })
+    .toBe(false);
+});
+
+test("Better Auth organization invite HTTP is not a public invite path", async ({ page }) => {
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  await expectBetterAuthInviteForbidden(page, `expo.ba-invite.${Date.now()}@auth-e2e.local`);
 });
 
 test("admin creates, bans, unbans, and authenticates a user", async ({ page, request }) => {
@@ -316,7 +490,7 @@ test("admin manages organization members from organization admin", async ({ page
   const membersAfterAdd = await trpc.auth.listAdminOrganizationMembers.query({
     organizationId: enterpriseOrgId,
   });
-  const member = membersAfterAdd.members.find((row) => row.user.email === email);
+  const member = membersAfterAdd.members.find((row) => row.user?.email === email);
   expect(member).toBeTruthy();
   await expect
     .poll(async () => {
@@ -355,6 +529,52 @@ test("admin manages organization members from organization admin", async ({ page
     .toBe(false);
 });
 
+test("admin transfers organization ownership to an active member", async ({ page, request }) => {
+  const email = `expo.org-owner.${Date.now()}@auth-e2e.local`;
+  const password = "password1234";
+  const childOrgName = `Expo Transfer Org ${Date.now()}`;
+
+  await createVerifiedExpoAccount(page, request, email, password);
+  await expoLoginNative(page, profiles[profile].adminEmail, profiles[profile].adminPassword);
+  const trpc = await createExpoTrpcClient(page, profile);
+  const childOrg = await trpc.auth.createOrganization.mutate({ name: childOrgName });
+
+  const users = await trpc.auth.searchAdminUsers.query({ q: email, limit: 10 });
+  const user = users.rows.find((row) => row.email === email);
+  expect(user).toBeTruthy();
+
+  await trpc.auth.addAdminOrganizationMember.mutate({
+    organizationId: childOrg.id,
+    userId: user?.id ?? "",
+    role: "member",
+  });
+  const membersAfterAdd = await trpc.auth.listAdminOrganizationMembers.query({
+    organizationId: childOrg.id,
+  });
+  const member = membersAfterAdd.members.find((row) => row.user?.email === email);
+  expect(member).toBeTruthy();
+
+  const transferred = await trpc.auth.transferOrganizationOwner.mutate({
+    organizationId: childOrg.id,
+    memberId: member?.id ?? "",
+  });
+  expect(transferred.owner).toEqual({ id: member?.id, role: "owner" });
+  expect(transferred.previousOwner.role).toBe("admin");
+
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.find((organization) => organization.id === childOrg.id)?.role;
+    })
+    .toBe("owner");
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, profiles[profile].adminEmail);
+      return state.organizations.find((organization) => organization.id === childOrg.id)?.role;
+    })
+    .toBe("admin");
+});
+
 test("admin organization pagination stays on the selected page", async ({ page, request }) => {
   const prefix = `Expo Pagination Org ${Date.now()}`;
   await seedOrganizations(request, profile, { prefix, count: 12 });

package/templates/minimal-app/apps/e2e/tests/helpers.ts.tpl

@@ -1,5 +1,8 @@
+import type { BackendTRPCRouter } from "@m5kdev/backend/types";
+import { transformer } from "@m5kdev/commons/utils/trpc";
 import type { APIRequestContext, Page, TestInfo } from "@playwright/test";
 import { expect } from "@playwright/test";
+import { createTRPCClient, httpBatchLink } from "@trpc/client";
 
 export type Profile = "standard" | "waitlist" | "expoStandard" | "expoWaitlist";
 
@@ -29,6 +32,7 @@ export type UserHarnessState = {
     type: string | null;
     parentId: string | null;
     role: string;
+    memberId: string;
   }>;
   credentialAccount: boolean;
   accountClaims: Array<{
@@ -48,7 +52,6 @@ export type UserHarnessState = {
     activeOrganizationMemberId: string | null;
     activeOrganizationRole: string | null;
     activeOrganizationType: string | null;
-    activeTeamId: string | null;
     impersonatedBy: string | null;
     createdAt: string;
   } | null;
@@ -287,3 +290,46 @@ export function resetTokenFrom(url: string) {
   if (!token) throw new Error(`Could not read reset token from ${url}`);
   return token;
 }
+
+export function memberEmail(member: {
+  email?: string | null;
+  user?: { email?: string | null } | null;
+}): string {
+  return (member.email ?? member.user?.email ?? "").trim().toLowerCase();
+}
+
+export function findMemberByEmail<
+  T extends {
+    email?: string | null;
+    user?: { email?: string | null } | null;
+  },
+>(members: readonly T[], email: string): T | undefined {
+  const needle = email.trim().toLowerCase();
+  return members.find((member) => memberEmail(member) === needle);
+}
+
+export async function createTrpcClient(page: Page, profile: Profile) {
+  const cookies = await page.context().cookies(profiles[profile].serverUrl);
+  const cookie = cookies.map((entry) => `${entry.name}=${entry.value}`).join("; ");
+  type FetchInit = NonNullable<Parameters<typeof fetch>[1]>;
+
+  return createTRPCClient<BackendTRPCRouter>({
+    links: [
+      httpBatchLink({
+        url: `${profiles[profile].serverUrl}/trpc`,
+        fetch(url, options) {
+          const headers = new Headers(options?.headers);
+          if (cookie) {
+            headers.set("cookie", cookie);
+          }
+          return fetch(url, {
+            ...options,
+            body: options?.body ? (options.body as FetchInit["body"]) : undefined,
+            headers,
+          });
+        },
+        transformer,
+      }),
+    ],
+  });
+}