create-m5kdev 0.40.3 → 0.41.1

package/package.json

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

package/templates/minimal-app/.github/workflows/check.yml.tpl

@@ -0,0 +1,21 @@
+name: check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.13.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm lint
+      - run: pnpm check-types

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

@@ -22,38 +22,29 @@
 // m5k:expo:end
 
 // m5k:server:start
-## Backend Conventions
-
-- Keep repository, service, and transport layers separate inside each module.
-- Register modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`.
-- Import Kernel infrastructure (`BaseModule`, Grants, DTOs) from `@m5kdev/backend/base/*`. The `modules/base` path still re-exports.
-- Clay, Docx, Pdf, Social, and Video are Optional Backend Module packages (`@m5kdev/module-<name>`). They are not scaffolded; add them only when the product needs them.
-- Use `BaseModule` subclasses for app modules; the kernel wires repositories, services, and tRPC.
-- Keep tRPC files focused on input/output wiring and delegate logic to services.
-- 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`.
-// m5k:server:end
+## Modules
+
+`posts` is the reference module. Mirror its layout when adding a feature:
 
+- `apps/shared/src/modules/posts/`
+- `apps/server/src/modules/posts/`
 // m5k:webapp:start
-## Frontend Conventions
-
-- Keep the app shell shape: `NuqsAdapter` + `BrowserRouter` + `Providers`.
-- Compose global providers only in `apps/webapp/src/Providers.tsx`.
-- Use `AppConfigProvider` and `AppTrpcQueryProvider` from `@m5kdev/frontend`; use `@m5kdev/web-ui` for web-only UI.
-- Define app roles in `apps/shared/src/modules/app/roles.constants.ts` and pass `roles: APP_ROLES_CONFIG` through `AppConfigProvider` and `createBackendApp` metadata.
-- Add role display labels in `apps/webapp/translations/app.json` using keys like `organization.role.editor` (resolved as `app:organization.role.editor`).
-- When adding custom roles, also extend module grants (for example `*.grants.ts`) so permissions match the new role keys.
-- For upgrading existing apps, see the docs site guide `apps/docs/docs/guides/custom-app-roles-migration.md`.
-- Use `nuqs` for URL state, React Router for routing, HeroUI for UI primitives, and Tailwind v4 for styling.
-- Prefer shared framework utilities from `@m5kdev/frontend` and `@m5kdev/web-ui` before adding local duplicates.
-- React 19 idioms: no `forwardRef` (pass `ref` as a prop), no `defaultProps`, use `startTransition`/`useDeferredValue` for low-priority updates.
-- Prefer HeroUI v3 components over hand-rolled HTML + Tailwind whenever an equivalent exists; Tailwind is for layout and styling on top of them.
-- Keep components display-focused: data fetching, mutations, URL state, and effect chains live in custom hooks under `modules/<feature>/hooks/` (small focused hooks composed into one screen-level hook, e.g. `usePostsRoute`). Ephemeral UI state (modal open, selected row) may stay in the component. Extract reusable tRPC actions (delete, publish) into their own hooks.
-- Fetch all server data with TanStack Query over tRPC (`useTRPC()` + `queryOptions`/`mutationOptions`); invalidate with the matching `queryFilter()` after mutations. No `fetch`/axios.
-- Forms are uncontrolled HeroUI `Form` + `TextField`/`TextArea` with native HTML validation (`isRequired`, `type`, `minLength`) and `FieldError`; read values from `FormData` on submit. Never add form libraries (react-hook-form, formik). Validation that HTML cannot express (e.g. confirm-password) happens in the submit handler.
-- All user-facing copy goes through i18next (`useTranslation`); keys live in `apps/webapp/translations/`.
-- The `posts` feature (`apps/webapp/src/modules/posts/`) is the reference implementation for these conventions; see `.cursor/rules/frontend-*.mdc` for the detailed guides.
+- `apps/webapp/src/modules/posts/`
 // m5k:webapp:end
 
+Read the matching `.cursor/rules` guide before editing a module file.
+// m5k:server:end
+
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues. Use the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default role labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one root `GLOSSARY.md` and `docs/adr/`. See `docs/agents/domain.md`.

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

@@ -139,6 +139,20 @@ The framework's detailed conventions live in `.cursor/rules/*.mdc`. Cursor appli
 | `.cursor/rules/frontend-i18n-guide.mdc` | webapp user-facing copy |
 // m5k:webapp:end
 
-`AGENTS.md` (repo root and per-app) carries a compact summary of the same conventions for other agents; this file plus the guides above are the authoritative version for Claude.
+`AGENTS.md` (repo root and per-app) points at this file and `.cursor/rules`. This file plus the guides above are the authoritative conventions.
 // m5k:server:end
 
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues. Use the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default role labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one root `GLOSSARY.md` and `docs/adr/`. See `docs/agents/domain.md`.
+

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

@@ -0,0 +1,181 @@
+# {{APP_NAME}}
+
+{{APP_DESCRIPTION}}
+
+## Language
+# m5k:server:start
+
+### Tenancy
+
+**Organization**:
+The default tenancy unit. Signup creates one; a Closed Organization cannot be used.
+_Avoid_: Workspace, tenant, account, company, Team
+
+**Membership**:
+A durable seat in an Organization. Invite can create it before a User exists; leave, cancel, and expiry soft-delete it; rejoin revives the same MemberId. An Organization has exactly one Owner.
+_Avoid_: OrgUser; treating Invitation as the Membership; Seat (that is Seat billing)
+
+**Member**:
+The Membership principal used to attribute and authorize org-scoped assets, including invited Memberships that do not yet have a User.
+_Avoid_: User (when you mean the membership), Invitation
+
+**MemberId**:
+The Membership id stamped on org-scoped rows. In organization context, `"own"` grants compare this, not UserId.
+_Avoid_: UserId as the org ownership key
+
+**User**:
+The global sign-in identity. Owns personal resources that are not org tenancy. A Closed User cannot sign in.
+_Avoid_: Account, Customer, Client, Member
+
+**UserId**:
+The User id. Correct key for personal resources. Not the org-scoped ownership key.
+_Avoid_: MemberId
+
+**Owner**:
+The Organization Role `owner`. Exactly one per Organization. Invite and org self-service cannot grant or transfer it.
+_Avoid_: multiple Owners as a product feature; inviting Owner
+
+**Invitation**:
+The accept token that attaches a User to an invited Membership. Not a person and not assignable.
+_Avoid_: Waitlist code, pending Member
+
+**Closed**:
+A User or Organization in the restorable lockout state.
+_Avoid_: soft-delete (that is Membership leave), deactivated, suspended, banned
+
+**Restore**:
+Returning a Closed User or Organization to usable state before Purge. Admin panel only.
+_Avoid_: undelete, reactivate
+
+**Purge**:
+Permanent removal of a Closed User or Organization after the grace window.
+_Avoid_: hard-delete as the User-facing noun
+
+### Identity and access
+
+**Actor**:
+Who a server call is made on behalf of: User, Organization, or Admin. Organization scope requires a live Membership and an Organization that is not Closed. Invited Members are not Actors.
+_Avoid_: Session, Principal, Request, TeamActor
+
+**Grant**:
+A permission tuple: resource, level (`user` | `organization`), role, Action, Access.
+_Avoid_: Permission, Policy, ACL
+
+**Action**:
+Canonical Grant verbs: `read`, `write`, `delete`, `publish`.
+_Avoid_: update, create, patch, remove
+
+**Access**:
+How wide a Grant is: `all`, `own`, `org`, `none`.
+_Avoid_: Scope, Role
+
+**Role**:
+A named key at User or Organization scope. Defaults: User `user`/`admin`; Organization `member`/`admin`/`owner`.
+_Avoid_: Grant, Access, permission
+
+### Product surfaces
+
+**Admin panel**:
+The User-role admin UI at `/admin`. Organization Role `admin` does not see it.
+_Avoid_: org Role admin, Billing Portal
+# m5k:files:start
+
+**File**:
+An inventoried object in storage: a row plus the bytes. Personal Files stamp UserId; org-scoped Files stamp MemberId.
+_Avoid_: Upload, Asset, Attachment, Blob
+# m5k:files:end
+# m5k:billing:start
+
+**Plan**:
+Named commercial offering in app code. Not a Stripe Product.
+_Avoid_: Product, Tier, Subscription
+
+**Subscription**:
+The billed relationship for an Organization, not a User.
+_Avoid_: Plan, personal User subscription
+
+**Checkout**:
+Hosted start of a Subscription when the Organization has none.
+_Avoid_: Billing Portal
+
+**Billing Portal**:
+Hosted management of an existing Subscription.
+_Avoid_: Checkout
+
+**Seat billing**:
+When on, billable quantity is the count of Memberships. Off (default): quantity is one.
+_Avoid_: Seat as a synonym for Membership
+# m5k:billing:end
+# m5k:ai:start
+
+**Conversation**:
+Ordered UI transcript of AI turns.
+_Avoid_: Chat, Thread (that is the store)
+
+**Thread**:
+The persisted AI memory thread behind a Conversation.
+_Avoid_: using Thread for the UI surface
+
+**Agent**:
+A named AI agent the app registers. A Conversation selects which Agent answers.
+_Avoid_: Assistant, Bot, MCP client
+# m5k:ai:end
+# m5k:mcp:start
+
+**MCP client**:
+A remote Model Context Protocol client that calls the app on behalf of a User.
+_Avoid_: Agent, Connection
+
+**MCP call**:
+A tRPC procedure opted into the MCP catalog. Grant checks always run.
+_Avoid_: a second tool catalog, Workflow job
+
+**MCP allowlist**:
+The Organizations a given OAuth client may pass as organizationId for a User.
+_Avoid_: treating allowlist as permission to write
+# m5k:mcp:end
+# m5k:notifications:start
+
+**Notification**:
+A persisted inbox instance owned by a Member, classified by a Notification kind.
+_Avoid_: UserId as the ownership key
+
+**Notification kind**:
+A developer-declared class of Notifications. Mute applies to the kind.
+_Avoid_: Notification (that is the instance)
+
+**Channel**:
+A delivery means for a Notification: in-app, web push, mobile push, or email.
+_Avoid_: Server event, Device
+# m5k:notifications:end
+# m5k:workflows:start
+
+**Workflow**:
+A persisted background run. Org-scoped runs stamp MemberId.
+_Avoid_: Job, Queue, Task, Recurrence
+# m5k:workflows:end
+# m5k:tags:start
+
+**Tag**:
+A polymorphic label. Ownership is UserId, MemberId, or organizationId.
+_Avoid_: Label, Category
+# m5k:tags:end
+# m5k:connect:start
+
+**Connection**:
+A linked third-party API account. Personal; keyed by UserId. The module id is `connect`.
+_Avoid_: Connect as the product noun; login OAuth
+# m5k:connect:end
+# m5k:webhook:start
+
+**Inbound callback**:
+A one-shot inbound callback with an awaitable payload. Unattributed. The module id is `webhook`.
+_Avoid_: Webhook (when you mean this vs Stripe Subscription sync); Connection
+# m5k:webhook:end
+# m5k:recurrence:start
+
+**Recurrence**:
+A repeating calendar pattern stored as a row. Not a Workflow.
+_Avoid_: Workflow, cron
+# m5k:recurrence:end
+# m5k:server:end

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

@@ -39,6 +39,8 @@ Database tables are registered by hand in `apps/server/src/schema.ts`; after cha
 
 - Email: `admin@{{APP_SLUG}}.local`
 - Password: `password1234`
+
+After sign-in, the index route (`/`) is the Posts list.
 // m5k:server:end
 
 ## Typical Commands

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

@@ -58,7 +58,7 @@ async function saveMemberEdit(page: Page, row: Locator, changes: { name?: string
     await dialog.getByLabel(/^name$/i).fill(changes.name);
   }
   if (changes.role !== undefined) {
-    await dialog.getByRole("button", { name: /^role$/i }).click();
+    await dialog.getByRole("button", { name: /role/i }).click();
     await page.getByRole("option", { name: new RegExp(`^${changes.role}$`) }).click();
   }
 
@@ -211,7 +211,10 @@ test("duplicate signup with an existing email is rejected", async ({ page, reque
   expect(
     response.ok(),
     `${response.status()} ${response.statusText()}: ${await response.text()}`
-  ).toBe(false);
+  ).toBe(true);
+  expect(await response.json()).toMatchObject({ token: null });
+  const state = await getUserState(request, profile, email);
+  expect(state.user.emailVerified).toBe(true);
 });
 
 test("organization invite email lets a new user join without creating a separate org", async ({
@@ -357,7 +360,7 @@ test("organization members page lets an admin edit a member name", async ({ page
   expect(afterName?.id).toBe(invitedMemberId);
   expect(afterName?.name).toBe("Kitchen lead");
   expect(afterName?.userId).toBeNull();
-  await expect(invitedRow.getByRole("cell").first()).toHaveText("Kitchen lead");
+  await expect(page.getByRole("row").filter({ hasText: "Kitchen lead" })).toBeVisible();
 });
 
 test("organization members page resends, updates, cancels, and revives an invited seat", async ({
@@ -491,9 +494,11 @@ test("admin creates, bans, unbans, and authenticates a user", async ({ page, req
   await dialog.getByPlaceholder(/enter user's email/i).fill(email);
   await dialog.getByPlaceholder(/enter password/i).fill(password);
   await dialog.getByRole("button", { name: /^create user$/i }).click();
+  await expect(dialog).toBeHidden();
 
+  await page.locator('input[name="search"]').fill(email);
   const createdRow = page.getByRole("row").filter({ hasText: email });
-  await expect(createdRow).toBeVisible();
+  await expect(createdRow).toBeVisible({ timeout: 10_000 });
   await expect(createdRow.getByText(/^verified$/i)).toBeVisible();
   await createdRow.getByLabel("User actions").click();
   await page.getByRole("menuitem", { name: /^ban$/i }).click();
@@ -529,21 +534,6 @@ test("admin creates, bans, unbans, and authenticates a user", async ({ page, req
     .toBe("admin");
 
   await logout(page);
-  const verificationResponse = await request.post(
-    `${profiles.standard.serverUrl}/api/auth/send-verification-email`,
-    {
-      data: {
-        email,
-        callbackURL: `${profiles.standard.webUrl}/login`,
-      },
-    }
-  );
-  expect(verificationResponse.ok()).toBe(true);
-  const verification = await latestEmail(request, profile, {
-    to: email,
-    templateId: "verification",
-  });
-  await request.get(emailUrl(verification));
   await login(page, email, password);
   const adminListResponse = await authFetch(page, profile, "/api/auth/admin/list-users");
   expect(
@@ -561,6 +551,7 @@ test("admin verifies email, changes user role, and sets password from users list
   const newPassword = "password5678";
 
   await signUp(page, email, password);
+  await expect(page.getByText(/verification email sent/i)).toBeVisible();
   const before = await getUserState(request, profile, email);
   expect(before.user.emailVerified).toBe(false);
   expect(before.user.role).toBe("user");
@@ -603,9 +594,7 @@ test("admin verifies email, changes user role, and sets password from users list
   await page.locator('input[name="search"]').fill(profiles.standard.adminEmail);
   const adminRow = page.getByRole("row").filter({ hasText: profiles.standard.adminEmail });
   await expect(adminRow).toBeVisible();
-  await expect(
-    adminRow.getByRole("button", { name: `Role for ${profiles.standard.adminEmail}` })
-  ).toBeDisabled();
+  await expect(adminRow.locator('[data-slot="select-trigger"]')).toBeDisabled();
 
   await logout(page);
   await login(page, email, newPassword);

package/templates/minimal-app/apps/server/drizzle/0009_empty_starjammers.sql

@@ -0,0 +1,45 @@
+DROP INDEX `users_stripe_customer_id_unique`;--> statement-breakpoint
+ALTER TABLE `users` ADD `closed_at` integer;--> statement-breakpoint
+ALTER TABLE `users` DROP COLUMN `stripe_customer_id`;--> statement-breakpoint
+PRAGMA foreign_keys=OFF;--> statement-breakpoint
+CREATE TABLE `__new_apikeys` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text,
+	`start` text,
+	`prefix` text,
+	`key` text NOT NULL,
+	`config_id` text DEFAULT 'default' NOT NULL,
+	`reference_id` text NOT NULL,
+	`user_id` text,
+	`refill_interval` integer,
+	`refill_amount` integer,
+	`last_refill_at` integer,
+	`enabled` integer NOT NULL,
+	`rate_limit_enabled` integer NOT NULL,
+	`rate_limit_time_window` integer,
+	`rate_limit_max` integer,
+	`request_count` integer NOT NULL,
+	`remaining` integer,
+	`last_request` integer,
+	`expires_at` integer,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	`permissions` text,
+	`metadata` text,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+INSERT INTO `__new_apikeys`("id", "name", "start", "prefix", "key", "config_id", "reference_id", "user_id", "refill_interval", "refill_amount", "last_refill_at", "enabled", "rate_limit_enabled", "rate_limit_time_window", "rate_limit_max", "request_count", "remaining", "last_request", "expires_at", "created_at", "updated_at", "permissions", "metadata") SELECT "id", "name", "start", "prefix", "key", 'default', "user_id", "user_id", "refill_interval", "refill_amount", "last_refill_at", "enabled", "rate_limit_enabled", "rate_limit_time_window", "rate_limit_max", "request_count", "remaining", "last_request", "expires_at", "created_at", "updated_at", "permissions", "metadata" FROM `apikeys`;--> statement-breakpoint
+DROP TABLE `apikeys`;--> statement-breakpoint
+ALTER TABLE `__new_apikeys` RENAME TO `apikeys`;--> statement-breakpoint
+PRAGMA foreign_keys=ON;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `currency` text;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `stripe_customer_id` text;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `stripe_sandbox_customer_id` text;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `billing_exempt` integer DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `allow_cardless_trial` integer DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE `organizations` ADD `cardless_trial_consumed` text DEFAULT '{}';--> statement-breakpoint
+ALTER TABLE `organizations` ADD `closed_at` integer;--> statement-breakpoint
+CREATE UNIQUE INDEX `organizations_stripe_customer_id_unique` ON `organizations` (`stripe_customer_id`);--> statement-breakpoint
+CREATE UNIQUE INDEX `organizations_stripe_sandbox_customer_id_unique` ON `organizations` (`stripe_sandbox_customer_id`);--> statement-breakpoint
+ALTER TABLE `files` DROP COLUMN `team_id`;