create-astram-app 0.9.1 → 0.9.2

package/README.md

@@ -216,6 +216,40 @@ With `auth: true`, check every item before the first production deploy.
   in-flight `/auth/refresh` per session). Concurrent refreshes of the same token can trip reuse
   detection, which revokes the session (the user must sign in again).
 
+## Upgrading from 0.9.x
+
+The next `@astram/identity` minor (KI #87) makes `shield_app.users.u_email` unique: identity
+migration `1710000000021-AddUsersEmailUniqueIndex` adds `UNIQUE INDEX uq_users_email`. Bump
+`@astram/identity` and `@astram/guard` (patch) in `server/package.json`, `npm install`, and run the
+migrations with the DDL account (`astram-migrate migrate`) before starting the new version.
+
+- **What counts as the same address** is the column collation, `utf8mb4_unicode_ci`: case,
+  trailing spaces, full-width letters, accents (`é` = `e`) and `ß` = `ss` all match. Leading
+  spaces and a trailing tab do not; the framework trims and lower-cases on write.
+- **Empty addresses:** the migration first sets empty or whitespace-only `u_email` to NULL (NULL
+  may repeat). `migrate:revert` drops the index but does not restore the empty strings.
+- **Out-of-order warning:** an app that already ran the dev seeds (`...099`/`...100`) sees
+  `WARNING out of order: pending migration 1710000000021`. That is expected; it is not a failure,
+  also under `--strict`.
+- **If it fails with duplicates:** the migration stops and lists each duplicate address MASKED
+  (`a***@example.com: 2 users`), with no user ids. Nothing is changed and no index is created.
+  Find the users (the admin user list searches by email), give each a distinct address or clear
+  it (`PUT /identity/users/:uuid`, or your own data fix as a migration), then run the migrations
+  again. The framework never picks which user keeps the address.
+- **After the upgrade:** a write of an address another user already holds fails in the database
+  (ER_DUP_ENTRY 1062) even when two requests race. The framework's own paths answer it: the
+  email-change confirm `409 email_unavailable`, `PUT /identity/users/:uuid` and
+  `POST /identity/users` 409 ("That username or email is already in use." — a taken username was
+  a 500 before). Because the collation folds accents, `ß` and width, `jose@example.com` and
+  `josé@example.com` are now the same address: the second one is refused with 409. If your own
+  code writes `shield_app.users` directly, handle errno 1062 as a conflict, and never log or
+  return the driver's message: it contains the full address.
+
+Run migration `1710000000021` in a low-traffic window on a large `users` table: it scans the table to
+normalise blank emails and holds those row locks until the index build commits. If it fails because
+a duplicate was written during the build (rather than at the pre-check), blank emails have already
+been set to NULL; resolve the reported addresses and re-run.
+
 ## Upgrading from 0.8.x
 
 create-astram-app 0.9.0 adds one lint rule (KI #82) and the verified email change (KI #14).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/server/package.json

@@ -24,7 +24,7 @@
     "@astram/engine": "^0.5.2",
     "@astram/guard": "^0.11.0",
     "@astram/guide": "^0.2.3",
-    "@astram/identity": "^0.8.0",
+    "@astram/identity": "^0.9.0",
     "@astram/migrate": "^0.3.2",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",