Merge pull request #227 from udecode/codex/226-expo-auth-site-url

Author: zbeyens

.changeset/expo-init-template.md

@@ -0,0 +1,11 @@
+---
+"kitcn": patch
+---
+
+Add `kitcn init -t expo` for a fresh Expo scaffold built on the official
+`create-expo-app` shell, including the Convex baseline, starter messages
+screen, and first-class `kitcn add auth` parity on the Expo scaffold.
+
+Expo local env now also owns `EXPO_PUBLIC_SITE_URL`, so Concave dev and Expo
+auth keep one local app-origin contract instead of drifting back to
+`http://localhost:3000`.

.gitignore

@@ -1,3 +1,4 @@
+CONTEXT.md
 .omx
 **/tsconfig.tsbuildinfo
 .netrc

CONTEXT.md

@@ -0,0 +1,96 @@
+# kitcn
+
+kitcn is a framework and CLI for bootstrapping Convex-first application
+surfaces. This context defines the product language for scaffold lanes and auth
+surfaces so new integrations do not invent parallel contracts.
+
+## Language
+
+**Default auth scaffold**:
+The first-class `kitcn add auth` capability that owns auth server, client,
+provider, and managed schema refresh behavior.
+_Avoid_: Standard auth, normal auth, main auth path
+
+**Raw Convex auth preset**:
+The conservative `kitcn add auth --preset convex` lane for plain Convex apps
+that do not adopt the full kitcn auth surface.
+_Avoid_: Convex auth parity, default auth
+
+**Expo auth parity**:
+Expo support that uses the **Default auth scaffold** product surface rather
+than introducing an Expo-only auth contract.
+_Avoid_: Expo auth preset, mobile-only auth mode
+
+**Managed auth schema refresh**:
+The `kitcn add auth --schema --yes` flow that refreshes auth-owned schema
+blocks without rerunning the full auth install.
+_Avoid_: auth regen, full auth rerun
+
+**Auth demo route**:
+The generated sign-in/sign-up screen owned by the **Default auth scaffold**.
+_Avoid_: sample auth page, temporary auth UI
+
+**Auth-aware provider wiring**:
+Client provider wiring that mounts the auth-capable Convex provider rather than
+the unauthenticated baseline provider.
+_Avoid_: auth bootstrap only, runtime-only auth
+
+**Generated auth contract**:
+The kitcn backend auth model built around `auth.config.ts`, `auth.ts`,
+`generated/auth`, and `kitcn/auth/http`.
+_Avoid_: component auth model, manual createClient auth model
+
+**Expo Better Auth client plugin**:
+The Better Auth Expo client plugin and native storage setup used in Expo
+clients.
+_Avoid_: generic web auth client, browser-only auth client
+
+## Relationships
+
+- **Expo auth parity** reuses the **Default auth scaffold**
+- **Expo auth parity** includes **Managed auth schema refresh**
+- **Expo auth parity** includes an **Auth demo route**
+- **Expo auth parity** includes **Auth-aware provider wiring**
+- **Expo auth parity** uses the **Generated auth contract**
+- **Expo auth parity** uses the **Expo Better Auth client plugin**
+- **Raw Convex auth preset** is distinct from the **Default auth scaffold**
+- The **Default auth scaffold** supports managed schema refresh via
+  `kitcn add auth --schema`
+- The **Raw Convex auth preset** does not use `--schema`; it refreshes by
+  rerunning the full preset command
+- The **Auth demo route** stays on `/auth` across first-class auth surfaces
+- Protected route groups are not part of **Expo auth parity** v1
+
+## Example dialogue
+
+> **Dev:** "For Expo, should we add a mobile auth preset?"
+> **Domain expert:** "No. Expo is **Expo auth parity**, which means the same
+> **Default auth scaffold** surface. The separate lane is only the **Raw Convex
+> auth preset**."
+
+> **Dev:** "After changing auth plugins for Expo, do we rerun full install?"
+> **Domain expert:** "No. Expo parity keeps **Managed auth schema refresh**,
+> just like the **Default auth scaffold**."
+
+> **Dev:** "Should Expo auth just wire the runtime and leave UI to users?"
+> **Domain expert:** "No. **Expo auth parity** owns the **Auth demo route** and
+> **Auth-aware provider wiring**, or parity means nothing."
+
+> **Dev:** "Do we port the old component-style auth API from
+> `convex-better-auth`?"
+> **Domain expert:** "No. Expo parity keeps the **Generated auth contract**.
+> `convex-better-auth` is the reference for native mechanics, not the public
+> product model."
+
+## Flagged ambiguities
+
+- "Expo auth" was ambiguous between **Expo auth parity** and the
+  **Raw Convex auth preset** — resolved: Expo uses **Expo auth parity**
+- "`--schema` support" was ambiguous between optional convenience and product
+  identity — resolved: it is part of **Expo auth parity** because Expo reuses
+  the **Default auth scaffold**
+- "Expo auth route" was ambiguous between generated UX and runtime-only wiring
+  — resolved: **Expo auth parity** owns an **Auth demo route** at `/auth`
+- "convex-better-auth as reference" was ambiguous between implementation donor
+  and public contract — resolved: it informs native mechanics, while kitcn
+  keeps the **Generated auth contract**

docs/adr/0001-expo-auth-parity.md

@@ -0,0 +1,7 @@
+# Expo auth uses the default auth scaffold, not a separate Expo preset
+
+Expo auth support will reuse the default `kitcn add auth` product surface,
+including `/auth` demo route ownership, auth-aware provider wiring, and
+`--schema` refresh. We explicitly rejected a separate Expo-only auth lane even
+though `../convex-better-auth` has Expo-specific mechanics, because that repo is
+the implementation reference for native behavior, not the public product model.

docs/brainstorms/2026-04-18-expo-template-requirements.md

@@ -0,0 +1,119 @@
+---
+date: 2026-04-18
+topic: expo-template
+---
+
+# Expo Template
+
+## Problem Frame
+
+`kitcn init -t` currently has web-first fresh-app scaffolds (`next`, `start`,
+`vite`) plus auth layering that assumes web/react project shapes. There is no
+first-class Expo lane, so mobile users either start elsewhere or force a web
+template into a native-shaped app.
+
+The goal is to add a first-party Expo template that feels like current kitcn
+templates: start from an official upstream shell, overlay the minimum kitcn
+Convex wiring, and prove the app is real with one tiny live demo. V1 should
+solve fresh mobile bootstrap only. It should not drag in auth, styling stack
+wars, or existing-app adoption.
+
+```mermaid
+flowchart TB
+    A["User runs `kitcn init -t expo --yes`"] --> B["kitcn creates app from official `create-expo-app` template"]
+    B --> C["kitcn overlays Convex config, env, and client wiring"]
+    C --> D["kitcn replaces starter content with one live messages demo screen"]
+    D --> E["User can run Expo app against Convex without extra manual setup"]
+```
+
+## Requirements
+
+**Official Base**
+- R1. `kitcn init -t expo` must scaffold from the official Expo CLI path rather
+  than from a kitcn-owned handwritten Expo shell.
+- R2. V1 must use `create-expo-app` as the source of truth for the app shell,
+  mirroring the repo's shadcn-owned Next approach.
+- R3. As of April 18, 2026, the intended upstream base is
+  `create-expo-app --template default@sdk-55`; planning must verify that this
+  still matches Expo's current official recommendation before implementation.
+
+**Generated App Shape**
+- R4. The generated app must be a fresh Expo Router app with a single-screen
+  shell, not tabs or drawer navigation.
+- R5. kitcn must overlay the minimum Convex runtime wiring needed for a working
+  native app instead of replacing the whole Expo project structure.
+- R6. The scaffolded app must include one live Convex-backed messages screen
+  with list and create behavior, matching the current tiny demo posture used in
+  other kitcn templates.
+- R7. The demo should replace upstream starter content enough that the scaffold
+  clearly reads as a kitcn+Convex app rather than a stock Expo welcome screen.
+
+**Scope and Compatibility**
+- R8. V1 must support fresh scaffolding only via `kitcn init -t expo`.
+- R9. V1 must not include auth scaffolding, auth-ready shell behavior, or
+  `kitcn add auth` support for Expo.
+- R10. V1 must not pick a styling system beyond the official Expo baseline; no
+  NativeWind, Unistyles, or other opinionated styling stack should be part of
+  the initial template.
+- R11. Planning must treat existing Expo app adoption as a separate future lane,
+  not as hidden scope inside this template work.
+
+**CLI Contract**
+- R12. `kitcn init` help, template validation, and machine-readable output must
+  recognize `expo` as a supported fresh-app template.
+- R13. Repo project detection and scaffold-context logic must gain an explicit
+  Expo/native lane rather than misclassifying Expo as generic React or leaving
+  it unsupported.
+- R14. The Expo template must preserve current kitcn expectations around
+  deterministic `--yes` behavior and fresh-app bootstrap flow.
+
+## Success Criteria
+- `kitcn init -t expo --yes` produces a runnable Expo app with Convex wired in.
+- The generated app opens to one live messages screen backed by Convex.
+- The implementation keeps Expo shell ownership upstream and keeps kitcn-owned
+  changes narrowly scoped to overlay files and minimal patch points.
+- V1 does not accidentally expand into auth, existing-app adoption, tabs/drawer
+  shells, or styling-framework decisions.
+
+## Scope Boundaries
+- No Expo auth support in v1.
+- No `kitcn add auth` Expo path in v1.
+- No existing Expo app adoption in v1.
+- No tabs or drawer starter shell in v1.
+- No NativeWind, Unistyles, or other opinionated mobile styling layer in v1.
+- No attempt to reuse `create-better-t-stack` as the generator source of truth.
+
+## Key Decisions
+- Official Expo base wins: use `create-expo-app`, not a kitcn-owned Expo shell.
+- kitcn overlays Convex onto the upstream app instead of replacing the app
+  structure wholesale.
+- V1 is fresh scaffold only: adoption work is deferred.
+- V1 is unauthenticated: auth is intentionally out of scope.
+- Demo shape is the existing tiny messages pattern: enough proof, low carrying
+  cost.
+- `create-better-t-stack` is a donor for Expo choices when useful, not the
+  baseline owner.
+
+## Dependencies / Assumptions
+- Expo's official template contract remains stable enough to wrap from the CLI.
+- The repo is willing to add a native/Expo project-context lane in CLI
+  detection and scaffold planning.
+- Convex's current React/React Native client surface is sufficient for a simple
+  Expo messages demo without introducing auth-specific runtime dependencies.
+
+## Outstanding Questions
+
+### Deferred to Planning
+- [Affects R1][Technical] Which exact files from the official Expo scaffold
+  should stay upstream-owned versus receive kitcn overlay patches?
+- [Affects R5][Technical] What is the smallest durable scaffold-context model
+  for Expo/native without contorting the current `next-app` vs `react` split?
+- [Affects R6][Technical] Which existing messages demo assets can be reused
+  directly versus needing Expo-native variants?
+- [Affects R12][Needs research] Which current CLI tests should be mirrored for
+  Expo template bootstrap, detection, and JSON output?
+- [Affects R3][Needs research] At implementation time, does Expo still
+  recommend `default@sdk-55`, or has the official template target changed?
+
+## Next Steps
+→ `/ce:plan` for structured implementation planning