@clubedge/create-clubedge-app 0.48.0 → 0.48.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.48.1
+
+- **Starter v0.31.2** by default (#214). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.31.2) cover:
+  - a new user's first requests at once, which get one users row instead of a 500 for all but one, in the Hono API, the FastAPI API, and the websites; a sync of the profile to an email address another user's row has still fails.
+- **Projects from Starter releases before v0.5.0 upgrade** (#206; issue #205). They record no modules, since those releases had none, and the CLI refused them as "created before create-clubedge-app 0.5.0", though 0.48.0 had created them. An upgrade now keeps Supabase Auth, S3 storage, and the Redis cache, which those releases built in and v0.5.0 made its first modules, and a note says so; modules that came later start as `none`. `add` and `remove` on such a project say to upgrade first.
+- **A dependency you only raised within its range, as `pnpm up` does, takes the Starter's new major or its removal** (#208; issue #207). After `pnpm up -r`, every upgrade to Starter v0.31.1 left a `package.json` conflict pnpm cannot read, such as `redis` `^5.12.2` against the Starter's `^6.3.1`, or a dependency the Starter moved to another package. A change that asks for less than your raise, such as a pin below it, still conflicts, and a range both sides raised still takes the higher one.
+- **A `pnpm patch` the change leaves unused is named before it stops `pnpm install`** (#210; issue #209). A patch made on a version the change moves away from stops the install with `ERR_PNPM_UNUSED_PATCH`. The CLI names it, with the range that leaves it out, skips the install, and says how to keep it: keyed by the package alone, pnpm applies it to whichever version it installs.
+- CI upgrades a project from Starter v0.4.0 and matches it against a fresh one (#206), and the tests that commit to Git have more time on Windows (#210).
+
 ## 0.48.0
 
 - **Starter v0.31.1** by default (#202). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.31.1) cover:

package/README.md

@@ -246,7 +246,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.31.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.31.2
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -267,7 +267,7 @@ pnpm clubedge add mobile expo                               # the native app; ad
 pnpm clubedge remove mobile
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.31.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.31.2 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -275,6 +275,8 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 - Files you never changed are updated, added, or deleted.
 - Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve. The Starter's whole new version of each such file is saved in `.clubedge/incoming/` to compare with yours (`git diff --no-index <file> .clubedge/incoming/<file>`); Git ignores that folder, so delete it when you are done.
 - `package.json` files merge by key, not by line: a script, dependency, or override you added next to the Starter's keeps both, and markers wrap only a key you both changed to different values, such as the same dependency's range. The file keeps your key order, indentation, and line endings.
+- A dependency's range that only one side raised within itself, as `pnpm up` does, gives way to the other side's change when that removes the dependency or asks for at least the raised version: the Starter's move to a new major, or its removal of a dependency it moved to another package, over your `pnpm up -r`. A range both sides raised within itself takes the higher one.
+- A `pnpm patch` made on a version the change moves away from would stop `pnpm install` (`ERR_PNPM_UNUSED_PATCH`). The CLI names each such patch and the range that leaves it out, and skips the install until it is fixed: keyed by the package alone, pnpm applies a patch to whichever version it installs.
 - Your own files are never touched.
 - Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local`, `apps/shell/.env.local`, or `apps/mobile/.env.local` when the project has them) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
 - `pnpm-lock.yaml` is replaced if you never changed your dependencies; otherwise `pnpm install` reconciles it.
@@ -416,27 +418,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.48.0
+create-clubedge-app v0.48.1
         |
         v
-Clubedge Starter v0.31.1
-commit 2fa0adfd67ef3511f577d11fdca4109cc8554759
+Clubedge Starter v0.31.2
+commit 2635acabc29de2eb3656bc9e6741eac8bd72cd38
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.48.0` | `clubedge-starter@v0.31.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.48.1` | `clubedge-starter@v0.31.2` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.31.1` tag is expected to resolve to commit
-`2fa0adfd67ef3511f577d11fdca4109cc8554759`. The CLI verifies this before
+The `v0.31.2` tag is expected to resolve to commit
+`2635acabc29de2eb3656bc9e6741eac8bd72cd38`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.31.1`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.31.2`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -491,7 +493,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.31.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.31.2`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/core/package-json-merge.js

@@ -61,10 +61,38 @@ function higherRange(a, b) {
             return n > (y[i] ?? 0) ? a : b;
     return a;
 }
+/**
+ * Whether `range` raises `base` within the versions `base` already allowed, as `pnpm up` does:
+ * ^5.8.0 to ^5.12.2. A raise like that only takes newer releases, so it is no edit of its own.
+ */
+const raisedWithin = (base, range) => typeof base === "string" && typeof range === "string" && range !== base && higherRange(base, range) === range;
+/** Whether a dependency map has the base's dependencies, each the same or only raised within its range. */
+const onlyRaised = (base, map) => isObject(base) &&
+    isObject(map) &&
+    Object.keys(map).length === Object.keys(base).length &&
+    Object.entries(map).every(([key, range]) => Object.hasOwn(base, key) && (same(base[key], range) || raisedWithin(base[key], range)));
+/** The lowest version a ^ or ~ range, or an exact version, allows; undefined for anything else. */
+function minimum(range) {
+    if (typeof range !== "string")
+        return undefined;
+    const match = SIMPLE_RANGE.exec(range) ?? /^()(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(range);
+    return match ? match.slice(2).map(Number) : undefined;
+}
+/** Whether `range` asks for at least the lowest version `than` allows: ^6.3.1 than ^5.12.2. */
+function atLeast(range, than) {
+    const [a, b] = [minimum(range), minimum(than)];
+    if (!a || !b)
+        return false;
+    const differs = a.findIndex((n, i) => n !== b[i]);
+    return differs === -1 || a[differs] > b[differs];
+}
 /**
  * One key's value, at `path` from the file's root: whoever changed it, or a conflict when both
  * did, differently. Objects both changed merge key by key; arrays and scalars are single values.
  * Undefined is a removed key. A dependency both raised within its range takes the higher range.
+ * One that a side only raised within its range, as `pnpm up` does, takes the other side's change
+ * when that removes it or asks for at least the raised version: the Starter's removal of a
+ * dependency, or its new major, over the project's `pnpm up`, and the other way round.
  */
 function merge(base, yours, theirs, path) {
     if (same(yours, theirs) || same(base, theirs))
@@ -73,6 +101,18 @@ function merge(base, yours, theirs, path) {
         return theirs;
     if (isObject(yours) && isObject(theirs))
         return mergeObjects(isObject(base) ? base : {}, yours, theirs, path);
+    if (holdsRanges(path.slice(0, -1))) {
+        const yoursRaised = raisedWithin(base, yours);
+        if (yoursRaised !== raisedWithin(base, theirs)) {
+            const [raised, other] = yoursRaised ? [yours, theirs] : [theirs, yours];
+            if (other === undefined || atLeast(other, raised))
+                return other;
+        }
+    }
+    // A whole dependency map one side only raised within its ranges, removed by the other side.
+    if (holdsRanges(path) && ((theirs === undefined && onlyRaised(base, yours)) || (yours === undefined && onlyRaised(base, theirs)))) {
+        return undefined;
+    }
     if (typeof yours === "string" && typeof theirs === "string" && holdsRanges(path.slice(0, -1))) {
         const higher = higherRange(yours, theirs);
         if (higher !== undefined)

package/dist/core/patches.js

@@ -0,0 +1,140 @@
+// pnpm stops `pnpm install` on a patch it does not use (ERR_PNPM_UNUSED_PATCH). `pnpm patch-commit`
+// keys a patch by the exact version it was made on, so a change that moves the dependency to a
+// range without that version leaves the patch unused, and the install stops. These find such
+// patches once the change is written, so the CLI can say which and what to do, instead of pnpm
+// stopping on them.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { listTemplateFiles, pathExists } from "../utils/fs.js";
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const RANGE = /^([\^~])(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/**
+ * Whether a range allows a version: an exact version, or a ^ or ~ range on a full version.
+ * Undefined for any other range, which this cannot tell.
+ */
+export function allows(range, version) {
+    const wanted = VERSION.exec(version)?.slice(1).map(Number);
+    if (!wanted)
+        return undefined;
+    const exact = VERSION.exec(range);
+    if (exact)
+        return exact[0] === version;
+    const match = RANGE.exec(range);
+    if (!match)
+        return undefined;
+    const floor = match.slice(2).map(Number);
+    // How many numbers the range keeps: ~ the major and minor, ^ up to its first one that is not 0.
+    const kept = match[1] === "~" ? 2 : floor.findIndex((n) => n !== 0) + 1 || 3;
+    if (floor.slice(0, kept).some((n, i) => n !== wanted[i]))
+        return false;
+    const differs = floor.findIndex((n, i) => n !== wanted[i]);
+    return differs === -1 || wanted[differs] > floor[differs];
+}
+/** `zod@4.6.5` or `@scope/pkg@1.2.3` into the package and its version; null for a key without an exact one. */
+function splitKey(key) {
+    const at = key.lastIndexOf("@");
+    if (at <= 0)
+        return null;
+    const [name, version] = [key.slice(0, at), key.slice(at + 1)];
+    return VERSION.test(version) ? { name, version } : null;
+}
+/** The patchedDependencies block of pnpm-workspace.yaml: indented `key: path` lines after its own line. */
+function workspacePatches(yaml) {
+    const lines = yaml.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^patchedDependencies:\s*(#.*)?$/.test(line));
+    if (start === -1)
+        return [];
+    const entries = [];
+    for (const line of lines.slice(start + 1)) {
+        if (!line.trim() || line.trim().startsWith("#"))
+            continue;
+        if (!/^\s/.test(line))
+            break;
+        const entry = /^\s+(['"]?)(.+?)\1\s*:\s*(['"]?)(.+?)\3\s*(#.*)?$/.exec(line);
+        if (entry)
+            entries.push([entry[2], entry[4]]);
+    }
+    return entries;
+}
+/** Every patch the project declares, with the file that declares it. */
+async function declaredPatches(root) {
+    const patches = [];
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        for (const [key, patch] of Object.entries(manifest.pnpm?.patchedDependencies ?? {})) {
+            if (typeof patch === "string")
+                patches.push({ key, patch, file: "package.json" });
+        }
+    }
+    catch {
+        // An unreadable package.json is reported elsewhere.
+    }
+    if (await pathExists(join(root, "pnpm-workspace.yaml"))) {
+        for (const [key, patch] of workspacePatches(await readFile(join(root, "pnpm-workspace.yaml"), "utf8"))) {
+            patches.push({ key, patch, file: "pnpm-workspace.yaml" });
+        }
+    }
+    return patches;
+}
+/** Each package's ranges across the workspace's package.json files; an override replaces them. */
+async function dependencyRanges(root) {
+    const ranges = new Map();
+    const overrides = {};
+    for (const path of (await listTemplateFiles(root)).filter((file) => /(^|\/)package\.json$/.test(file))) {
+        let manifest;
+        try {
+            manifest = JSON.parse(await readFile(join(root, path), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (path === "package.json")
+            Object.assign(overrides, manifest.pnpm?.overrides ?? {});
+        for (const field of ["dependencies", "devDependencies", "optionalDependencies"]) {
+            for (const [name, range] of Object.entries(manifest[field] ?? {})) {
+                if (typeof range === "string")
+                    ranges.set(name, [...(ranges.get(name) ?? []), range]);
+            }
+        }
+    }
+    for (const [name, range] of Object.entries(overrides)) {
+        if (typeof range === "string" && ranges.has(name))
+            ranges.set(name, [range]);
+    }
+    return ranges;
+}
+/**
+ * Patches keyed by an exact version that none of the project's ranges for the package allows,
+ * which pnpm would leave unused. A patch on a package no package.json names (a dependency of a
+ * dependency), or with a range this cannot read, is left out: pnpm decides those.
+ */
+export async function unusedPatches(root) {
+    const declared = await declaredPatches(root);
+    if (!declared.length)
+        return [];
+    const ranges = await dependencyRanges(root);
+    const unused = [];
+    for (const { key, patch, file } of declared) {
+        const parsed = splitKey(key);
+        const own = parsed ? ranges.get(parsed.name) : undefined;
+        if (!parsed || !own?.length)
+            continue;
+        if (own.every((range) => allows(range, parsed.version) === false))
+            unused.push({ key, ...parsed, patch, file, ranges: own });
+    }
+    return unused;
+}
+/** What to tell the developer about patches pnpm would not use, and how to keep them. */
+export function unusedPatchWarning(patches, installSkipped) {
+    const lines = patches.map(({ key, name, patch, file, ranges }) => `  ${key} (${patch}, in ${file}): the project now asks for ${name} ${[...new Set(ranges)].join(" or ")}`);
+    const [first] = patches;
+    // The key by the package alone, written as its file writes keys.
+    const byName = first.file === "package.json"
+        ? `"${first.name}": "${first.patch}"`
+        : `${first.name.startsWith("@") ? `'${first.name}'` : first.name}: ${first.patch}`;
+    return [
+        `${installSkipped ? "Skipped `pnpm install`: it would stop" : "`pnpm install` will stop"} on ${patches.length === 1 ? "a patch" : "patches"} made for a version the change moves away from (ERR_PNPM_UNUSED_PATCH):`,
+        ...lines,
+        `To try ${patches.length === 1 ? "it" : "each"} on the new version, key it by the package alone in ${first.file}, as \`${byName}\`: pnpm then applies it to the version it installs, and says so if it no longer fits. Or make it again with \`pnpm patch ${first.name}\`. Then run \`pnpm install\`.`,
+    ].join("\n");
+}

package/dist/core/project.js

@@ -57,10 +57,8 @@ export async function readProject(directory) {
             }
             const origin = manifest.clubedge;
             if (origin?.starterRef) {
-                // Projects record the framework only when the Starter offered a choice, but always their modules.
-                if (!origin.modules) {
-                    throw new ProjectError("This project was created before create-clubedge-app 0.5.0 and does not record its modules, so it cannot be changed automatically.");
-                }
+                // Projects record the framework only when the Starter offered a choice, and their modules
+                // when it had any: a project from Starter v0.4.0 or earlier records none.
                 return {
                     root: current,
                     identity: {
@@ -73,7 +71,7 @@ export async function readProject(directory) {
                     starterRef: origin.starterRef,
                     starterCommit: origin.starterCommit,
                     stacks: recordedStacks(origin),
-                    modules: origin.modules,
+                    modules: origin.modules && typeof origin.modules === "object" ? origin.modules : {},
                     services: origin.services && typeof origin.services === "object" ? origin.services : {},
                 };
             }

package/dist/modify.js

@@ -12,6 +12,7 @@ import { runsServer } from "./core/manifest-fields.js";
 import { readTemplateManifest } from "./core/manifest.js";
 import { compareVersions } from "./core/health.js";
 import { countConflicts } from "./core/merge.js";
+import { unusedPatches, unusedPatchWarning } from "./core/patches.js";
 import { describeReleases, fetchReleases, releasesBetween } from "./core/releases.js";
 import { moduleChoices, NO_STACK, selectModules, selectStacks, slotChoices, stacksIn } from "./core/plan.js";
 import { readProject } from "./core/project.js";
@@ -319,6 +320,12 @@ export function changedSelection(manifest, project, command, cli) {
 export function changedModules(manifest, project, command, cli) {
     return changedSelection(manifest, project, command, cli).modules;
 }
+/**
+ * What Starters before v0.5.0 built in: Supabase Auth, S3 storage, and a Redis cache. v0.5.0 made
+ * them its first modules, with these options as defaults. Projects from those Starters record no
+ * modules, and an upgrade keeps these rather than taking them out as modules the project predates.
+ */
+export const BUILT_IN_BEFORE_MODULES = { auth: "supabase", storage: "s3", cache: "redis" };
 /**
  * The project's selection in a newer Starter. Modules the project predates get their "none"
  * option where there is one, so an upgrade never adds a service on its own.
@@ -476,8 +483,16 @@ async function planChange(project, command, base, baseManifest, target, cli) {
     if (target.commit && target.commit === project.starterCommit)
         return null;
     const targetManifest = await readTemplateManifest(target.root);
-    const { modules, introduced, dropped } = upgradedModules(targetManifest, project, cli);
+    // A Starter before modules built in what became the first ones, and its project keeps them.
+    const builtIn = !Object.keys(baseManifest.modules).length && Object.keys(targetManifest.modules).length > 0;
+    const keptModules = Object.fromEntries(Object.entries(BUILT_IN_BEFORE_MODULES).filter(([id]) => targetManifest.modules[id]));
+    const recorded = builtIn ? { ...project, modules: keptModules } : project;
+    const { modules, introduced, dropped } = upgradedModules(targetManifest, recorded, cli);
     const notes = dropped.map((id) => `Starter ${target.ref} no longer has the ${id} module; its files are merged away like any other change.`);
+    if (builtIn && Object.keys(keptModules).length) {
+        const kept = Object.entries(keptModules).map(([id, option]) => `${targetManifest.modules[id].name}: ${targetManifest.modules[id].options[option]?.name ?? option}`);
+        notes.unshift(`Starter ${project.starterRef} had no modules yet, but built in what became the first ones, so the project keeps them: ${kept.join(", ")}. Switch one with: ${cli} add <module> <option>`);
+    }
     if (/^v\d/.test(target.ref)) {
         notes.push(`Release notes: https://github.com/${target.repository}/releases/tag/${target.ref}`);
     }
@@ -619,6 +634,18 @@ export async function changeProject(args) {
         progress.stop("Starter ready");
         spinning = false;
         const cli = await cliCommand(project);
+        // Every project records the Starter's modules when it has any, so none recorded against a
+        // Starter with modules means package.json lost them, and the project's files can't be told apart.
+        const starterModules = Object.keys(baseManifest.modules);
+        if (!Object.keys(project.modules).length && starterModules.length) {
+            throw new UsageError(`package.json does not record this project's modules, which Starter ${project.starterRef} has, so the CLI cannot tell which of their files the project has. ` +
+                `Add them to its "clubedge" field, as "modules": { "${starterModules[0]}": "<option>", ... } with one entry for each of ${starterModules.join(", ")}, then run this again.`);
+        }
+        // Starters before v0.5.0 have no modules or apps to change; their projects upgrade first.
+        if (!upgrading && !starterModules.length && !appSlots(baseManifest).length) {
+            throw new UsageError(`Starter ${project.starterRef}, which this project comes from, has no modules or apps to ${command.name}: they came in later releases. ` +
+                `Upgrade the project first with \`${cli} upgrade\`, then ${command.name} them.`);
+        }
         const complete = command.name === "upgrade" ? command : await completeCommand(baseManifest, project, command, interactive);
         if (!complete) {
             outro("Cancelled; nothing was changed.");
@@ -651,9 +678,14 @@ export async function changeProject(args) {
         // The files are written now, so what is left to resolve is reported even when the install fails.
         let installError;
         const manifests = await conflictedManifests(project.root);
+        // A patch pnpm would not use stops the install, so it is reported, and the install left until it is fixed.
+        const unused = manifests.length ? [] : await unusedPatches(project.root);
         if (manifests.length) {
             log.warn(conflictedManifestWarning(manifests, args.install));
         }
+        else if (unused.length) {
+            log.warn(unusedPatchWarning(unused, args.install));
+        }
         else if (args.install) {
             const { pnpm, problem } = await detectPnpm();
             if (pnpm) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.48.0",
+  "version": "0.48.1",
   "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -24,8 +24,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.31.1",
-    "starterCommit": "2fa0adfd67ef3511f577d11fdca4109cc8554759"
+    "starterRef": "v0.31.2",
+    "starterCommit": "2635acabc29de2eb3656bc9e6741eac8bd72cd38"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/api",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/api-fastapi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/api-fastapi",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/api-fastapi/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clubedge-api"
-version = "0.31.1"
+version = "0.31.2"
 description = "The project's API, implementing packages/contract/openapi.yaml."
 requires-python = ">=3.12"
 dependencies = [

package/template/apps/api-fastapi/src/clubedge_api/users.py

@@ -5,26 +5,31 @@ reference it, such as subscriptions, delete their rows with it."""
 from clubedge_api.contract import User
 from clubedge_api.db import connect
 
+FIND_USER = "select id from users where auth_user_id = %s limit 1"
+
 
 async def ensure_user_id(user: User) -> str:
     """The users row id for the signed-in user. Reads first, so requests that only need the id
     don't write; creates the row when it is missing."""
     async with connect() as db:
-        cursor = await db.execute(
-            "select id from users where auth_user_id = %s limit 1", (user["id"],)
-        )
+        cursor = await db.execute(FIND_USER, (user["id"],))
         row = await cursor.fetchone()
         if row is None:
+            # Without a conflict target, every unique index settles the race between a user's
+            # first requests, which can insert at once: one inserts the row, the others read it.
             cursor = await db.execute(
                 "insert into users (auth_user_id, email) values (%s, %s)"
-                " on conflict (auth_user_id) do update"
-                " set email = excluded.email, updated_at = now()"
-                " returning id",
+                " on conflict do nothing returning id",
                 (user["id"], user["email"]),
             )
             row = await cursor.fetchone()
+            if row is None:
+                cursor = await db.execute(FIND_USER, (user["id"],))
+                row = await cursor.fetchone()
     if row is None:
-        raise RuntimeError("The users row was not created.")
+        raise RuntimeError(
+            "Another users row has this user's email address, so it can't have one of its own."
+        )
     return str(row[0])
 
 

package/template/apps/api-fastapi/tests/test_users.py

@@ -27,10 +27,28 @@ def test_creates_the_users_row_when_it_is_missing(monkeypatch: pytest.MonkeyPatc
     assert asyncio.run(users.ensure_user_id(USER)) == "row-2"
     [_, (insert, params)] = db.statements
     assert insert.startswith("insert into users (auth_user_id, email) values (%s, %s)")
-    assert "on conflict (auth_user_id) do update" in insert
+    # No conflict target: every unique index, the email's too, settles a race.
+    assert insert.endswith(" on conflict do nothing returning id")
     assert params == ("user-1", "ada@example.com")
 
 
+def test_reads_the_row_another_first_request_created(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Two first requests at once: the insert does nothing, and the other request's row is read.
+    db = database(monkeypatch, None, None, ("row-3",))
+    assert asyncio.run(users.ensure_user_id(USER)) == "row-3"
+    assert [statement for statement, _ in db.statements] == [
+        users.FIND_USER,
+        db.statements[1][0],
+        users.FIND_USER,
+    ]
+
+
+def test_says_so_when_another_users_row_has_the_email(monkeypatch: pytest.MonkeyPatch) -> None:
+    database(monkeypatch, None, None, None)
+    with pytest.raises(RuntimeError, match="Another users row has this user's email address"):
+        asyncio.run(users.ensure_user_id(USER))
+
+
 def test_reads_and_writes_the_display_name(monkeypatch: pytest.MonkeyPatch) -> None:
     db = database(monkeypatch, ("Ada",), None)
     assert asyncio.run(users.get_display_name("row-1")) == "Ada"

package/template/apps/api-fastapi/uv.lock

@@ -389,7 +389,7 @@ wheels = [
 
 [[package]]
 name = "clubedge-api"
-version = "0.31.1"
+version = "0.31.2"
 source = { editable = "." }
 default-groups = "all"
 dependencies = [

package/template/apps/capacitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/capacitor",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/expo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/expo",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "main": "expo-router/entry",

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/vite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/vite",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {

package/template/deploy/cloudflare/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/deploy-cloudflare",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/auth-appwrite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-appwrite",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Appwrite provider for @clubedge/auth, run from the server with an API key and session cookies.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-better-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-better-auth",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Better Auth adapter for @clubedge/auth, storing users and sessions in your own PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-firebase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-firebase",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Firebase Authentication provider for @clubedge/auth, run from the server with session cookies.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-supabase",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Supabase Auth adapter for @clubedge/auth.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache-redis",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Redis rate limiter and cache for @clubedge/cache.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/contract",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/core",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/db",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/src/users.test.ts

@@ -4,7 +4,13 @@ import { migrate } from "drizzle-orm/pglite/migrator";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import type { Database } from "./client";
-import { deleteUserProfile, ensureUserId, getDisplayName, setDisplayName } from "./users";
+import {
+  deleteUserProfile,
+  ensureUserId,
+  getDisplayName,
+  setDisplayName,
+  upsertUserProfile,
+} from "./users";
 
 /** A fresh PostgreSQL (PGlite) with the app's migrations applied. */
 async function database() {
@@ -28,6 +34,53 @@ describe("user profiles", () => {
     expect(await getDisplayName(db, id)).toBeNull();
   }, 30_000);
 
+  it("gives a user's first requests at once the same row", async () => {
+    const db = await database();
+    const ids = await Promise.all([1, 2, 3, 4].map(() => ensureUserId(db, profile)));
+    expect(new Set(ids).size).toBe(1);
+    const synced = await Promise.all([1, 2].map(() => upsertUserProfile(db, profile)));
+    expect(synced).toEqual([ids[0], ids[0]]);
+  }, 30_000);
+
+  it("reads the row of a user's first request that inserted it at once with this one", async () => {
+    const db = await database();
+    const id = await ensureUserId(db, profile);
+    // PGlite runs one statement at a time, so two inserts never race here. This stands in for
+    // the one that lost: the other request's row is in, and the email's unique index stopped it.
+    const lost = Object.assign(new Error("duplicate key value violates unique constraint"), {
+      code: "23505",
+    });
+    const racing: Database = Object.create(db, {
+      insert: {
+        value: () => {
+          throw lost;
+        },
+      },
+    });
+    expect(await upsertUserProfile(racing, profile)).toBe(id);
+    await expect(
+      upsertUserProfile(racing, { ...profile, email: "grace@example.com" }),
+    ).rejects.toBe(lost);
+  }, 30_000);
+
+  it("leaves an email address another user's row has to that row", async () => {
+    const db = await database();
+    const id = await ensureUserId(db, profile);
+    await ensureUserId(db, { authUserId: "another-user", email: "grace@example.com" });
+    await expect(
+      upsertUserProfile(db, { ...profile, email: "grace@example.com" }),
+    ).rejects.toMatchObject({ cause: { code: "23505" } });
+    expect(await upsertUserProfile(db, profile)).toBe(id);
+  }, 30_000);
+
+  it("says so when another user's row has the email address, which is unique", async () => {
+    const db = await database();
+    await ensureUserId(db, profile);
+    await expect(ensureUserId(db, { ...profile, authUserId: "another-user" })).rejects.toThrow(
+      "Another users row has this user's email address, so it can't have one of its own.",
+    );
+  }, 30_000);
+
   it("deletes a profile by its identity-provider user", async () => {
     const db = await database();
     const id = await ensureUserId(db, profile);

package/template/packages/db/src/users.ts

@@ -2,20 +2,61 @@ import { eq } from "drizzle-orm";
 import type { Database } from "./client";
 import { users } from "./schema";
 
+/** The users row of an identity-provider user, if it has one. */
+async function findUser(
+  db: Database,
+  authUserId: string,
+): Promise<{ id: string; email: string } | undefined> {
+  const [row] = await db
+    .select({ id: users.id, email: users.email })
+    .from(users)
+    .where(eq(users.authUserId, authUserId))
+    .limit(1);
+  return row;
+}
+
+/** Whether an error is PostgreSQL's unique violation (23505), as the driver or Drizzle raises it. */
+function isUniqueViolation(error: unknown): boolean {
+  const code = (value: unknown) =>
+    typeof value === "object" && value !== null && "code" in value ? value.code : undefined;
+  const cause =
+    typeof error === "object" && error !== null && "cause" in error ? error.cause : undefined;
+  return code(error) === "23505" || code(cause) === "23505";
+}
+
+/**
+ * The users row of another identity-provider user has this one's email address, which is
+ * unique, so this user can't have a row of its own.
+ */
+function emailTaken(): Error {
+  return new Error(
+    "Another users row has this user's email address, so it can't have one of its own.",
+  );
+}
+
 /** Creates or updates the app-owned profile row for an identity-provider user; returns its id. */
 export async function upsertUserProfile(
   db: Database,
   profile: { authUserId: string; email: string },
 ): Promise<string> {
-  const [row] = await db
-    .insert(users)
-    .values(profile)
-    .onConflictDoUpdate({
-      target: users.authUserId,
-      set: { email: profile.email, updatedAt: new Date() },
-    })
-    .returning({ id: users.id });
-  return row!.id;
+  try {
+    const [row] = await db
+      .insert(users)
+      .values(profile)
+      .onConflictDoUpdate({
+        target: users.authUserId,
+        set: { email: profile.email, updatedAt: new Date() },
+      })
+      .returning({ id: users.id });
+    return row!.id;
+  } catch (error) {
+    // A user's first requests can insert at once. The conflict target settles only auth_user_id,
+    // so the email's unique index stops all but one, whose row the others then read. A row with
+    // another address means the index stopped an update to one that another user's row has.
+    const row = isUniqueViolation(error) ? await findUser(db, profile.authUserId) : undefined;
+    if (row?.email === profile.email) return row.id;
+    throw error;
+  }
 }
 
 /**
@@ -26,12 +67,18 @@ export async function ensureUserId(
   db: Database,
   profile: { authUserId: string; email: string },
 ): Promise<string> {
-  const [row] = await db
-    .select({ id: users.id })
-    .from(users)
-    .where(eq(users.authUserId, profile.authUserId))
-    .limit(1);
-  return row?.id ?? upsertUserProfile(db, profile);
+  const existing = await findUser(db, profile.authUserId);
+  if (existing) return existing.id;
+  // Without a conflict target, every unique index settles the race between a user's first
+  // requests, which can insert at once: one inserts the row, and the others read it.
+  const [created] = await db
+    .insert(users)
+    .values(profile)
+    .onConflictDoNothing()
+    .returning({ id: users.id });
+  const id = created?.id ?? (await findUser(db, profile.authUserId))?.id;
+  if (!id) throw emailTaken();
+  return id;
 }
 
 /** The display name the user chose, or null. */

package/template/packages/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Email interface, console and in-memory providers, and message templates.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-resend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-resend",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Resend provider for @clubedge/email, through Resend's HTTP API.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-smtp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-smtp",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "SMTP provider for @clubedge/email, for any SMTP server.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Background jobs interface: job definitions, a queue contract, and an in-memory queue.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-bullmq/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-bullmq",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "BullMQ provider for @clubedge/jobs: a job queue stored in Redis.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-inngest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-inngest",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Inngest provider for @clubedge/jobs: jobs run by Inngest, which calls the app for each one.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-pg-boss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-pg-boss",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "pg-boss provider for @clubedge/jobs: a job queue stored in the project's PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/local-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/local-db",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "PostgreSQL for development without Docker: PGlite served over the PostgreSQL protocol.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/mobile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/mobile",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "The mobile app's native helpers, through Capacitor, and its own screens: the update notice and the demo.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Observability interface: error reports and spans for @clubedge/core's telemetry hooks, and an in-memory provider for tests.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-otel",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "OpenTelemetry provider for @clubedge/observability: traces and error logs exported over OTLP to any collector.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-sentry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-sentry",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Sentry provider for @clubedge/observability: server and browser errors, traces, and source map uploads.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Provider-neutral payments: the PaymentProvider interface, billing logic, and subscription tables.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments-stripe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments-stripe",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Stripe provider for @clubedge/payments: Checkout, the customer portal, and verified webhooks.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/push/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/push",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Provider-neutral push notifications: the PushProvider interface, the devices table, and sending to a user's devices.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/push-expo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/push-expo",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Expo's push service for @clubedge/push: notifications to the native app's Expo push tokens.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/push-native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/push-native",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "FCM and APNs for @clubedge/push: notifications sent straight to Android's and Apple's push services.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/storage-s3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-s3",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "S3-compatible adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-supabase",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Supabase Storage adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/ui",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.31.1",
-  "commit": "2fa0adfd67ef3511f577d11fdca4109cc8554759",
+  "ref": "v0.31.2",
+  "commit": "2635acabc29de2eb3656bc9e6741eac8bd72cd38",
   "files": [
     ".dockerignore",
     ".env.example",