Merge branch 'dev' into inline-product-cancelling

Author: BilalG1

.vscode/settings.json

@@ -7,6 +7,7 @@
   "typescript.tsdk": "node_modules/typescript/lib",
   "editor.tabSize": 2,
   "cSpell.words": [
+    "glassmorphic",
     "sparkline",
     "Clickhouse",
     "pushable",

AGENTS.md

@@ -23,7 +23,7 @@ You should ALWAYS add new E2E tests when you change the API or SDK interface. Ge
 - **Run some tests**: `pnpm test run <file-filters>`
 
 ### Database Commands
-- **Generate migration**: `pnpm db:migration-gen`
+- **Generate migration**: `pnpm db:migration-gen` — NOTE: don't forget to create tests for the migrations!
 - **Reset database** (rarely used): `pnpm db:reset`
 - **Seed database** (rarely used): `pnpm db:seed`
 - **Initialize database** (rarely used): `pnpm db:init`
@@ -100,8 +100,12 @@ To see all development ports, refer to the index.html of `apps/dev-launchpad/pub
 - NEVER implement a hacky solution without EXPLICIT approval from the user. Always go the extra mile to make sure the solution is clean, maintainable, and robust.
 - Fail early, fail loud. Fail fast with an error instead of silently continuing.
 - Do NOT use `as`/`any`/type casts or anything else like that to bypass the type system unless you specifically asked the user about it. Most of the time a place where you would use type casts is not one where you actually need them. Avoid wherever possible.
-- When writing database migration files, assume that we have >1,000,000 rows in every table (unless otherwise specified). This means you may have to use CONDITIONALLY_REPEAT_MIGRATION_SENTINEL to avoid running the migration and things like concurrent index builds; see the existing migrations for examples.
+- When writing database migration files, assume that we have >1,000,000 rows in every table (unless otherwise specified). This means you may have to use CONDITIONALLY_REPEAT_MIGRATION_SENTINEL to avoid running the migration and things like concurrent index builds; see the existing migrations for examples. One common pattern is to add a temporary extra boolean column
+- Each migration file runs in its own transaction with a relatively short timeout. Split long-running operations into separate migration files to avoid timeouts. For example, when adding CHECK constraints, use `NOT VALID` in one migration, then `VALIDATE CONSTRAINT` in a separate migration file.
+- Note that each database migration file is executed in a single transaction. Even with the run-outside-transaction sentinel, the transaction will still continue during the entire migration file. If you want to split things up into multiple transactions, put it into their own migration files.
+- When writing database migration files, ALWAYS ALWAYS add tests for all the potential edge cases! See the folder structure of the other migrations to see how that works.
 - **When building frontend code, always carefully deal with loading and error states.** Be very explicit with these; some components make this easy, eg. the button onClick already takes an async callback for loading state, but make sure this is done everywhere, and make sure errors are NEVER just silently swallowed.
+- Any design components you add or modify in the dashboard, update the Playground page accordingly to showcase the changes.
 - Unless very clearly equivalent from types, prefer explicit null/undefinedness checks over boolean checks, eg. `foo == null` instead of `!foo`.
 
 ### Code-related

CLAUDE.md

@@ -67,6 +67,7 @@ STACK_S3_REGION=
 STACK_S3_ACCESS_KEY_ID=
 STACK_S3_SECRET_ACCESS_KEY=
 STACK_S3_BUCKET=
+STACK_S3_PRIVATE_BUCKET=
 
 # AWS configuration
 STACK_AWS_REGION=

apps/backend/.env

@@ -58,6 +58,8 @@ STACK_OPENAI_API_KEY=mock_openai_api_key
 STACK_STRIPE_SECRET_KEY=sk_test_mockstripekey
 STACK_STRIPE_WEBHOOK_SECRET=mock_stripe_webhook_secret
 
+STACK_OPENROUTER_API_KEY=mock-openrouter-api-key
+
 # Email monitor configuration for tests
 STACK_EMAIL_MONITOR_VERIFICATION_CALLBACK_URL=http://localhost:8101/handler/email-verification
 STACK_EMAIL_MONITOR_PROJECT_ID=internal
@@ -74,6 +76,7 @@ STACK_S3_REGION=us-east-1
 STACK_S3_ACCESS_KEY_ID=s3mockroot
 STACK_S3_SECRET_ACCESS_KEY=s3mockroot
 STACK_S3_BUCKET=stack-storage
+STACK_S3_PRIVATE_BUCKET=stack-storage-private
 
 # AWS region defaults to LocalStack
 STACK_AWS_REGION=us-east-1

apps/backend/.env.development

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-backend",
-  "version": "2.8.67",
+  "version": "2.8.68",
   "repository": "https://github.com/stack-auth/stack-auth",
   "private": true,
   "type": "module",

apps/backend/package.json

@@ -0,0 +1,31 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const tenancyId = randomUUID();
+  const userId1 = randomUUID();
+  const userId2 = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+  await sql`INSERT INTO "Tenancy" ("id", "createdAt", "updatedAt", "projectId", "branchId", "hasNoOrganization") VALUES (${tenancyId}::uuid, NOW(), NOW(), ${projectId}, 'main', 'TRUE'::"BooleanTrue")`;
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${userId1}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${userId2}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+
+  return { projectId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const rows = await sql`
+    SELECT "restrictedByAdmin", "restrictedByAdminReason"
+    FROM "ProjectUser"
+    WHERE "mirroredProjectId" = ${ctx.projectId}
+  `;
+
+  expect(rows).toHaveLength(2);
+  for (const row of rows) {
+    expect(row.restrictedByAdmin).toBe(false);
+    expect(row.restrictedByAdminReason).toBeNull();
+  }
+};

apps/backend/prisma/migrations/20260201400000_add_restricted_by_admin_fields/tests/default-values.ts

@@ -0,0 +1,60 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const tenancyId = randomUUID();
+  const unrestricted = randomUUID();
+  const restrictedWithReason = randomUUID();
+  const restrictedNoReason = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+  await sql`INSERT INTO "Tenancy" ("id", "createdAt", "updatedAt", "projectId", "branchId", "hasNoOrganization") VALUES (${tenancyId}::uuid, NOW(), NOW(), ${projectId}, 'main', 'TRUE'::"BooleanTrue")`;
+
+  // Unrestricted user (valid: false + null reason)
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${unrestricted}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+
+  // Restricted with reason
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin", "restrictedByAdminReason") VALUES (${restrictedWithReason}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW(), true, 'spam')`;
+
+  // Restricted without reason
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin") VALUES (${restrictedNoReason}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW(), true)`;
+
+  return { projectId, tenancyId, unrestricted, restrictedWithReason, restrictedNoReason };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  // Existing valid rows should still be there
+  const rows = await sql`
+    SELECT "projectUserId", "restrictedByAdmin", "restrictedByAdminReason", "restrictedByAdminPrivateDetails"
+    FROM "ProjectUser"
+    WHERE "mirroredProjectId" = ${ctx.projectId}
+    ORDER BY "projectUserId"
+  `;
+  expect(rows).toHaveLength(3);
+
+  for (const row of rows) {
+    expect(row.restrictedByAdminPrivateDetails).toBeNull();
+  }
+
+  // Restricted user can have private details set
+  await sql`UPDATE "ProjectUser" SET "restrictedByAdminPrivateDetails" = 'internal notes' WHERE "projectUserId" = ${ctx.restrictedWithReason}::uuid`;
+
+  // INVALID: unrestricted user with a reason should fail
+  await expect(sql`
+    UPDATE "ProjectUser" SET "restrictedByAdminReason" = 'should fail' WHERE "projectUserId" = ${ctx.unrestricted}::uuid
+  `).rejects.toThrow(/ProjectUser_restricted_by_admin_consistency/);
+
+  // INVALID: unrestricted user with private details should fail
+  await expect(sql`
+    UPDATE "ProjectUser" SET "restrictedByAdminPrivateDetails" = 'should fail' WHERE "projectUserId" = ${ctx.unrestricted}::uuid
+  `).rejects.toThrow(/ProjectUser_restricted_by_admin_consistency/);
+
+  // VALID: new restricted user with all fields
+  const newUser = randomUUID();
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin", "restrictedByAdminReason", "restrictedByAdminPrivateDetails") VALUES (${newUser}::uuid, ${ctx.tenancyId}::uuid, ${ctx.projectId}, 'main', NOW(), NOW(), NOW(), true, 'test', 'details')`;
+
+  // VALID: un-restricting clears reason and details
+  await sql`UPDATE "ProjectUser" SET "restrictedByAdmin" = false, "restrictedByAdminReason" = NULL, "restrictedByAdminPrivateDetails" = NULL WHERE "projectUserId" = ${newUser}::uuid`;
+};

apps/backend/prisma/migrations/20260201400001_add_restricted_by_admin_constraint/tests/constraint-enforcement.ts

@@ -0,0 +1,27 @@
+-- Add deferred retry fields for email sending
+-- These fields allow the email queue to schedule retries for later iterations
+-- instead of blocking the current iteration with inline retries.
+
+ALTER TABLE "EmailOutbox"
+  ADD COLUMN "sendRetries" INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN "nextSendRetryAt" TIMESTAMP(3),
+  ADD COLUMN "sendAttemptErrors" JSONB;
+
+-- Constraint: nextSendRetryAt can only be set after at least one failed attempt
+-- (if sendRetries is 0, no attempt has failed, so there's nothing to retry)
+-- Use NOT VALID to avoid holding ACCESS EXCLUSIVE lock during full-table validation.
+-- Validation happens in a separate migration to avoid transaction timeout.
+ALTER TABLE "EmailOutbox"
+  ADD CONSTRAINT "EmailOutbox_nextSendRetryAt_requires_failure"
+  CHECK ("nextSendRetryAt" IS NULL OR "sendRetries" > 0) NOT VALID;
+
+-- Constraint: sendAttemptErrors can only be set after at least one failed attempt
+ALTER TABLE "EmailOutbox"
+  ADD CONSTRAINT "EmailOutbox_sendAttemptErrors_requires_failure"
+  CHECK ("sendAttemptErrors" IS NULL OR "sendRetries" > 0) NOT VALID;
+
+-- Constraint: nextSendRetryAt must be null when email has finished sending
+-- (if finishedSendingAt is set, there's nothing more to retry)
+ALTER TABLE "EmailOutbox"
+  ADD CONSTRAINT "EmailOutbox_no_retry_after_finished"
+  CHECK ("finishedSendingAt" IS NULL OR "nextSendRetryAt" IS NULL) NOT VALID;

apps/backend/prisma/migrations/20260210000000_deferred_email_retry/migration.sql

@@ -0,0 +1,7 @@
+-- Validate the deferred retry constraints added in the previous migration.
+-- This runs in a separate transaction to avoid timeout, and only takes
+-- SHARE UPDATE EXCLUSIVE lock (allows concurrent reads/writes).
+
+ALTER TABLE "EmailOutbox" VALIDATE CONSTRAINT "EmailOutbox_nextSendRetryAt_requires_failure";
+ALTER TABLE "EmailOutbox" VALIDATE CONSTRAINT "EmailOutbox_sendAttemptErrors_requires_failure";
+ALTER TABLE "EmailOutbox" VALIDATE CONSTRAINT "EmailOutbox_no_retry_after_finished";