@ramonclaudio/create-vexpo 0.1.3 → 0.1.4

package/README.md

@@ -3,7 +3,9 @@
 [![npm](https://img.shields.io/npm/v/@ramonclaudio/create-vexpo)](https://www.npmjs.com/package/@ramonclaudio/create-vexpo)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Scaffold a new [vexpo](https://github.com/ramonclaudio/vexpo) project: Expo SDK 56 + Convex + Better Auth + Resend, wired end-to-end for iOS. Real auth (email + password, email OTP, Apple Sign In), APNs push, OTA updates, App Store submission. Strict TypeScript, native SwiftUI via `@expo/ui/swift-ui`, no NativeWind.
+Scaffold a new [vexpo](https://github.com/ramonclaudio/vexpo) project: an Expo SDK 56 iOS app with Convex, Better Auth, and Resend wired in for backend, auth, and email. Push, OTA updates, and App Store submission all run through EAS.
+
+This is the opinionated stack I reach for on every new app, Expo and Convex and Better Auth sitting on top of EAS, and I wanted anyone to be able to start from it without a day of wiring. The CLI walks you through creating a Convex account or linking one you already have, so you go from empty folder to a running app without leaving the terminal.
 
 ## Usage
 
@@ -20,31 +22,39 @@ cd my-app
 
 npx vexpo lite         # 60 seconds: Convex + Better Auth, simulator-ready
 npx vexpo lite --new   # same + Convex signup walkthrough for first-time users
-npx vexpo full         # full provisioning: TestFlight-ready (Convex, Better Auth, Resend, Apple Sign In, EAS, rebrand)
-npx vexpo full --new   # same + Apple/Convex/Expo/Resend signup walkthrough
+npx vexpo full         # full provisioning: TestFlight-ready
+npx vexpo full --new   # same + Apple, Convex, Expo, and Resend signup walkthrough
 ```
 
-`npx vexpo lite` is the dev-mode shortcut. No Apple Developer account, no domain, no EAS, no Resend. Boots in the iOS Simulator in ~60 seconds. Add `--new` if you don't have a Convex account yet.
+`npx vexpo lite` is the dev-mode shortcut. No Apple Developer account, no domain, no EAS, no Resend. Boots in the iOS Simulator in about 60 seconds. Add `--new` if you don't have a Convex account yet.
+
+`npx vexpo full` validates and provisions everything in order: Convex, Better Auth, Resend, Apple Sign In, EAS, and a rebrand. About 30 minutes hands-on plus Apple-side wait times. It prints the `eas build` command at the end for you to run when ready.
 
-`npx vexpo full` walks Apple Developer / Expo / Convex / Resend signups (with `--new`), validates each, provisions everything in order. ~30 minutes hands-on plus Apple-side wait times. Prints the canonical `eas build` command at the end. You run it when ready.
+## Pre-reqs
+
+- macOS with Xcode, to build and run the app in the iOS Simulator.
+- Bun, or Node 20+.
+- An Apple Developer membership, only when you ship to TestFlight or the App Store. Not needed for local dev with `npx vexpo lite`.
 
 ## Options
 
-| Flag            | Behavior                                                                                      |
-| --------------- | --------------------------------------------------------------------------------------------- |
-| `[directory]`   | Project directory name (positional). Defaults to `my-vexpo-app` with `-y`, otherwise prompts. |
-| `--no-install`  | Skip running `<pm> install` after copying the template.                                       |
-| `--no-git`      | Skip `git init` after install.                                                                |
-| `--no-setup`    | Skip the post-install `npx vexpo lite` / `npx vexpo full` prompt.                             |
-| `-y, --yes`     | Accept defaults, skip prompts.                                                                |
-| `-v, --version` | Print version, exit.                                                                          |
+| Flag            | Behavior                                                                   |
+| --------------- | -------------------------------------------------------------------------- |
+| `[directory]`   | Project directory name (positional). Defaults to `my-vexpo-app` with `-y`. |
+| `--no-install`  | Skip installing dependencies after copying the template.                   |
+| `--no-git`      | Skip `git init` after install.                                             |
+| `--no-setup`    | Skip the printed next-steps block after install.                           |
+| `-y, --yes`     | Accept defaults, skip prompts.                                             |
+| `-v, --version` | Print version, exit.                                                       |
 
 ## What gets scaffolded
 
-The CLI copies `templates/default/` from the published tarball, restores npm-stripped dotfiles (`.gitignore`, `.env.example`, `.npmrc`, etc.), rewrites `package.json` (project name, version, drops monorepo metadata), installs dependencies via the detected package manager (`npm`, `bun`, `pnpm`, or `yarn`, sniffed from `npm_config_user_agent`; defaults to `npm`), and initializes a fresh git repo with `feat: initial commit`. No lockfile ships in the tarball: the first install resolves the template's ranges fresh (including the latest in-range `vexpo` CLI) and the generated lockfile lands in the initial commit.
+The CLI copies `templates/default/`, restores the dotfiles npm strips from tarballs (`.gitignore`, `.env.example`, `.npmrc`, others), and rewrites `package.json` for the new project. It installs with the package manager it detects from `npm_config_user_agent` (`npm`, `bun`, `pnpm`, or `yarn`, defaulting to `npm`). Then it initializes a git repo with `feat: initial commit`.
 
-After that, the project is standalone. The operational CLI (`vexpo`) is installed as a devDependency, so `npx vexpo <subcommand>` resolves to the local pinned version. Setup commands aren't in `package.json`. They're one-shot CLI invocations, not runtime scripts.
+No lockfile ships in the tarball. The first install resolves the template's ranges fresh, including the latest in-range `vexpo` CLI, and the generated lockfile lands in the initial commit. The `vexpo` CLI installs as a devDependency, so `npx vexpo <subcommand>` resolves to the local pinned version.
 
 ## Repo
 
 [github.com/ramonclaudio/vexpo](https://github.com/ramonclaudio/vexpo)
+
+Development happens in the monorepo. See [CONTRIBUTING.md](https://github.com/ramonclaudio/vexpo/blob/main/CONTRIBUTING.md) on GitHub.

package/dist/index.js

@@ -11,7 +11,7 @@ import prompts from 'prompts';
 
 // package.json
 var package_default = {
-  version: "0.1.3"};
+  version: "0.1.4"};
 
 // src/index.ts
 var here = dirname(fileURLToPath(import.meta.url));
@@ -19,7 +19,7 @@ var TEMPLATE_DIR = join(here, "templates", "default");
 async function main() {
   const program = new Command().name("create-vexpo").description(
     "Scaffold a new vexpo project. Expo SDK 56 + Convex + Better Auth + Resend, wired for iOS."
-  ).argument("[directory]", "project directory name").option("--no-install", "skip installing dependencies").option("--no-git", "skip git init").option("--no-setup", "skip the `npx vexpo lite` / `npx vexpo full` prompt after install").option("-y, --yes", "accept defaults, skip prompts").version(package_default.version, "-v, --version").parse();
+  ).argument("[directory]", "project directory name").option("--no-install", "skip installing dependencies").option("--no-git", "skip git init").option("--no-setup", "skip the printed next-steps block after install").option("-y, --yes", "accept defaults, skip prompts").version(package_default.version, "-v, --version").parse();
   const flags = program.opts();
   const argDir = program.args[0];
   intro();
@@ -43,30 +43,50 @@ Target ${target} already exists. Pick a different name.`));
     copySpin.fail("Template copy failed");
     throw err;
   }
+  let depsReady = !flags.install;
   if (flags.install) {
     const installSpin = ora(`Installing dependencies with ${kleur.cyan(pm)}`).start();
     try {
-      await execa(pm, ["install"], { cwd: target, stdio: "ignore" });
+      await execa(pm, ["install"], { cwd: target, stdout: "ignore" });
       installSpin.succeed(`Installed with ${pm}`);
-    } catch {
-      installSpin.warn(`Install skipped. Run ${kleur.cyan(`${pm} install`)} manually.`);
+      depsReady = true;
+    } catch (err) {
+      installSpin.fail(`Install failed. Run ${kleur.cyan(`${pm} install`)} manually.`);
+      const stderr = installFailureStderr(err);
+      if (stderr) console.error(kleur.gray(tail(stderr)));
     }
   }
   if (flags.git) {
     const gitSpin = ora("Initializing git").start();
     try {
       await execa("git", ["init", "--initial-branch=main"], { cwd: target, stdio: "ignore" });
-      await execa("git", ["add", "-A"], { cwd: target, stdio: "ignore" });
-      await execa("git", ["commit", "-m", "feat: initial commit", "--no-gpg-sign"], {
-        cwd: target,
-        stdio: "ignore"
-      });
-      gitSpin.succeed("Git repo initialized");
+      if (depsReady) {
+        await execa("git", ["add", "-A"], { cwd: target, stdio: "ignore" });
+        const identity = await execa("git", ["config", "user.email"], {
+          cwd: target,
+          reject: false
+        });
+        if (identity.exitCode !== 0 || !identity.stdout.trim()) {
+          gitSpin.warn("Git repo initialized, commit skipped (no git identity)");
+          console.error(
+            kleur.gray("  Set git config user.name and user.email, then commit yourself.")
+          );
+        } else {
+          await execa("git", ["commit", "-m", "feat: initial commit", "--no-gpg-sign"], {
+            cwd: target,
+            stdio: "ignore"
+          });
+          gitSpin.succeed("Git repo initialized");
+        }
+      } else {
+        gitSpin.warn("Git repo initialized, commit skipped (install failed)");
+        console.error(kleur.gray(`  Commit yourself after ${pm} install lands.`));
+      }
     } catch {
       gitSpin.warn("Git init skipped");
     }
   }
-  if (flags.setup) nextSteps(target, flags, pm);
+  if (flags.setup) nextSteps(target, pm, depsReady);
 }
 var NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 var NAME_HINT = "lowercase letters, numbers, dashes; must start alphanumeric";
@@ -157,12 +177,22 @@ function intro() {
   console.log();
   console.log(kleur.bold().cyan("create-vexpo") + kleur.gray(` v${package_default.version}`));
 }
-function nextSteps(target, flags, pm) {
+function installFailureStderr(err) {
+  if (err && typeof err === "object" && "stderr" in err) {
+    const stderr = err.stderr;
+    if (typeof stderr === "string") return stderr.trim();
+  }
+  return "";
+}
+function tail(text, n) {
+  return text.split("\n").slice(-20).join("\n");
+}
+function nextSteps(target, pm, depsReady) {
   const cdPath = relative(process.cwd(), target) || ".";
   console.log();
   console.log(kleur.bold("Next steps:"));
   console.log(kleur.gray("  cd ") + kleur.cyan(cdPath));
-  if (!flags.install) console.log(kleur.gray(`  ${pm} install`));
+  if (!depsReady) console.log(kleur.gray(`  ${pm} install`));
   console.log(
     kleur.gray(
       `  npx vexpo lite     ${kleur.dim("# dev mode: Convex + Better Auth, 60s to simulator")}`

package/dist/templates/default/.eas/workflows/e2e-tests.yml

@@ -11,6 +11,9 @@ name: E2E tests
 # `MAESTRO_APP_ID` resolves to the project's bundle id from the EAS development
 # environment (populated by `vexpo full` or `eas env:create`). The flow
 # yaml at .maestro/launch.yaml reads it as `appId: ${MAESTRO_APP_ID}`.
+#
+# The auth flow (.maestro/auth.yaml) signs a fresh account up against the
+# dev Convex deployment, so `test_creds` mints a unique email per run.
 
 # Auto-run on PRs is OFF by default to conserve EAS build credits (each run
 # builds an iOS Simulator binary). Trigger manually, or restore the
@@ -30,13 +33,23 @@ jobs:
       platform: ios
       profile: development:simulator
 
+  test_creds:
+    name: Mint unique test credentials
+    outputs:
+      email: ${{ steps.creds.outputs.email }}
+    steps:
+      - id: creds
+        run: set-output email "maestro-e2e-$(date +%s)@example.com"
+
   maestro:
     name: Run Maestro flows
-    needs: [build_ios_simulator]
+    needs: [build_ios_simulator, test_creds]
     type: maestro
     environment: development
     env:
       MAESTRO_APP_ID: ${{ env.EXPO_PUBLIC_APP_BUNDLE_ID }}
+      MAESTRO_TEST_EMAIL: ${{ needs.test_creds.outputs.email }}
+      MAESTRO_TEST_PASSWORD: maestro-e2e-password
     params:
       build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
       flow_path: [".maestro"]

package/dist/templates/default/.eas/workflows/rotate-apple-jwt.yml

@@ -1,8 +1,8 @@
 name: Rotate Apple Sign In JWT
 
-# Apple caps client_secret JWTs at 180 days. We re-sign every 90 days so
-# we always have plenty of headroom and never get caught with an expired
-# token. Replaces the GitHub Actions equivalent. runs on EAS infrastructure
+# Apple caps client_secret JWTs at 180 days. We re-sign quarterly (the 1st of
+# Jan, Apr, Jul, Oct) so we always have plenty of headroom and never get caught
+# with an expired token. Replaces the GitHub Actions equivalent. runs on EAS infrastructure
 # and reads secrets from EAS env vars (production, secret visibility) rather
 # than GitHub repo secrets.
 #

package/dist/templates/default/.maestro/auth.yaml

@@ -0,0 +1,229 @@
+# Auth journey: sign up (auto-verify lite path) -> land authed -> sign out -> sign back in.
+#
+# This deployment has REQUIRE_EMAIL_VERIFICATION unset, so `getEnabledProviders`
+# returns emailFeatures: false. Sign-up creates a verified account and Better
+# Auth's autoSignIn returns a session in the same call, so there is no OTP step:
+# the user lands signed in. A fresh signed-in user trips the first-launch gate
+# in (app)/_layout.tsx and gets redirected to /welcome; this flow completes that
+# onboarding before asserting the tabs.
+#
+# Same @expo/ui SwiftUI conventions as launch.yaml: `testID` maps to the native
+# accessibilityIdentifier and surfaces to Maestro as `resource-id`, so id-based
+# asserts/taps resolve. Driving notes carry over:
+#   - ProminentButton submits hold content in the center, so tap them by `id`.
+#   - Segmented Picker rows put their label text in the middle, so tap the
+#     sign-in/sign-up toggle by its label text (`tapOn: "Sign up"`), not by id.
+#   - The sign-out row is a full-width Button with its label in the center, so
+#     tap it by `id`.
+#   - waitForAnimationToEnd between navigations; assert-then-tap for tab bars.
+#   - Use extendedWaitUntil with a generous timeout after sign-up/sign-in: those
+#     hit the live Convex deployment over the network.
+#
+# Env vars:
+#   MAESTRO_APP_ID        bundle id (EAS injects from EXPO_PUBLIC_APP_BUNDLE_ID)
+#   MAESTRO_TEST_EMAIL    unique email per run (a fresh account is created)
+#   MAESTRO_TEST_PASSWORD password, at least 10 chars (signUpSchema)
+#
+# Local re-runs: Better Auth keeps the session in the keychain, which
+# clearState does NOT wipe. Reset it first or the relaunch comes up signed in:
+#   xcrun simctl keychain booted reset
+#
+# Run locally (needs a JDK on PATH):
+#   MAESTRO_APP_ID=$(grep '^EXPO_PUBLIC_APP_BUNDLE_ID=' .env.local | cut -d= -f2) \
+#     MAESTRO_TEST_EMAIL="e2e+$(date +%s)@example.com" \
+#     MAESTRO_TEST_PASSWORD="maestro-test-pw" \
+#     maestro test .maestro/auth.yaml
+# Run on EAS: via `.eas/workflows/e2e-tests.yml` (workflow_dispatch only).
+appId: ${MAESTRO_APP_ID}
+---
+- launchApp:
+    clearState: true
+- waitForAnimationToEnd:
+    timeout: 15000
+
+# Dev-client builds: clearState also wipes the dev client's last-opened-bundle
+# memory, so the launcher shows the server picker instead of the app. Tap the
+# running Metro server when the picker appears. Release builds skip this block.
+- runFlow:
+    when:
+      visible: "DEVELOPMENT SERVERS"
+    commands:
+      - tapOn:
+          text: "http://.*:8081"
+      - waitForAnimationToEnd:
+          timeout: 15000
+
+# Dev-client builds also show a one-time "developer menu" intro sheet after
+# clearState. Drag it down to dismiss. Release builds skip this block too.
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# The intro sheet can appear late while Metro is still bundling, so check a
+# second time after the bundle settles.
+- waitForAnimationToEnd:
+    timeout: 10000
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# Signed out: the auth guard mounts the `auth` group, whose stack starts at
+# sign-in. Wait for the screen root before touching anything.
+- extendedWaitUntil:
+    visible:
+      id: "sign-in-screen"
+    timeout: 20000
+# Inner SwiftUI Text testIDs do not surface to Maestro (Host roots and real
+# controls do), so static copy is asserted by its text.
+- assertVisible: "Enter your credentials.*"
+
+# Cross to sign-up via the segmented toggle. Tap the segment by label text, not
+# id (the Picker row holds its label in the middle).
+- tapOn: "Sign up"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "sign-up-screen"
+    timeout: 15000
+- assertVisible: "Create your account"
+
+# Fill name, email, password. Username is optional and skipped. Tapping the
+# field by id focuses it, then `inputText` types into the focused field.
+# The keyboard covers the lower fields once it is up. Both auth screens use
+# scrollDismissesKeyboard("interactively"), so a downward drag dismisses the
+# keyboard between fields (hideKeyboard is flaky on iOS, don't use it).
+- tapOn:
+    id: "sign-up-name"
+- inputText: "Maestro E2E"
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- scrollUntilVisible:
+    element:
+      id: "sign-up-email"
+    direction: DOWN
+- tapOn:
+    id: "sign-up-email"
+- inputText: ${MAESTRO_TEST_EMAIL}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- scrollUntilVisible:
+    element:
+      id: "sign-up-password"
+    direction: DOWN
+# iOS Automatic Strong Password hijacks SecureFields with newPassword content
+# type in the simulator and swallows typed input. The eye toggle swaps to a
+# plain TextField (and auto-focuses it), which types fine.
+- tapOn:
+    id: "sign-up-password-visibility"
+- waitForAnimationToEnd:
+    timeout: 3000
+- tapOn:
+    id: "sign-up-password"
+- inputText: ${MAESTRO_TEST_PASSWORD}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+
+# Submit. ProminentButton center holds content, so tap by id.
+- scrollUntilVisible:
+    element:
+      id: "sign-up-submit"
+    direction: DOWN
+- tapOn:
+    id: "sign-up-submit"
+
+# Auto-verify lite path: account is created verified and the session returns in
+# the same call, so the app signs in. A fresh authed user is redirected to the
+# first-launch welcome onboarding. Generous timeout: this is a live network call.
+- extendedWaitUntil:
+    visible:
+      id: "welcome-screen"
+    timeout: 30000
+
+# Complete onboarding. Three steps; the button is "Next" until the last step,
+# then "Get Started" (both share id welcome-continue). Skip jumps straight to
+# the app. Tap Skip by label text to dismiss the gate in one move.
+- assertVisible: "Skip"
+- tapOn: "Skip"
+- waitForAnimationToEnd:
+    timeout: 5000
+
+# Authenticated: the tabs root mounts on home.
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 20000
+
+# Sign out via Settings. Native tab taps can be flaky, so assert-then-tap.
+- assertVisible: "Settings"
+- tapOn: "Settings"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# The sign-out row is a capsule row (label left, Spacer center), so tap by text.
+- tapOn: "Sign out"
+- waitForAnimationToEnd:
+    timeout: 3000
+# Confirm in the native ConfirmationDialog. The action label is "Sign Out"
+# (capital O), distinct from the row's "Sign out".
+- assertVisible: "Sign Out"
+- tapOn: "Sign Out"
+
+# Back to the unauthenticated entry.
+- extendedWaitUntil:
+    visible:
+      id: "sign-in-screen"
+    timeout: 20000
+
+# Sign back in with the same credentials. Method toggle defaults to Email.
+- tapOn:
+    id: "sign-in-email"
+- inputText: ${MAESTRO_TEST_EMAIL}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+# Same strong-password autofill dodge as sign-up: reveal, which auto-focuses.
+- tapOn:
+    id: "sign-in-email-password-visibility"
+- waitForAnimationToEnd:
+    timeout: 3000
+- tapOn:
+    id: "sign-in-email-password"
+- inputText: ${MAESTRO_TEST_PASSWORD}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- scrollUntilVisible:
+    element:
+      id: "sign-in-submit"
+    direction: DOWN
+- tapOn:
+    id: "sign-in-submit"
+
+# Authenticated again. Onboarding was already marked seen, so this lands on the
+# tabs root directly. Generous timeout: live network call.
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 30000
+
+- takeScreenshot: auth-final

package/dist/templates/default/.maestro/launch.yaml

@@ -12,12 +12,12 @@
 # not by `id`, or the tap lands on empty space. Native tab-bar taps can be flaky;
 # assert-then-tap or retry.
 #
-# Maestro auto-derives the appId from the build's bundle id, so the same flow
-# runs against the dev simulator binary (`com.example.<pkg>` fallback in
-# app.config.ts) and the production binary (`com.<your-team>.<app>`) without edits.
+# `appId` reads ${MAESTRO_APP_ID}. EAS injects it from EXPO_PUBLIC_APP_BUNDLE_ID
+# (see .eas/workflows/e2e-tests.yml), so the same flow runs against any fork's
+# bundle id without edits. Locally, pass it from .env.local (needs a JDK on PATH):
 #
-# Run locally: `maestro test .maestro/launch.yaml`
-# Run on EAS:  triggered by `.eas/workflows/e2e-tests.yml` on every PR.
+# Run locally: MAESTRO_APP_ID=$(grep '^EXPO_PUBLIC_APP_BUNDLE_ID=' .env.local | cut -d= -f2) maestro test .maestro/launch.yaml
+# Run on EAS:  via `.eas/workflows/e2e-tests.yml` (workflow_dispatch only).
 appId: ${MAESTRO_APP_ID}
 ---
 - launchApp: