@ramonclaudio/create-vexpo 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# create-vexpo
+
+[![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.
+
+## Usage
+
+```bash
+npm create @ramonclaudio/vexpo@latest my-app
+# or
+bunx @ramonclaudio/create-vexpo@latest my-app
+```
+
+After scaffold:
+
+```bash
+cd my-app
+
+bunx vexpo lite         # 60 seconds: Convex + Better Auth, simulator-ready
+bunx vexpo lite --new   # same + Convex signup walkthrough for first-time users
+bunx vexpo full         # full provisioning: TestFlight-ready (Convex, Better Auth, Resend, Apple Sign In, EAS, rebrand)
+bunx vexpo full --new   # same + Apple/Convex/Expo/Resend signup walkthrough
+```
+
+`bunx 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.
+
+`bunx 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.
+
+## 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 `bunx vexpo lite` / `bunx vexpo full` prompt.                           |
+| `-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`, etc.), rewrites `package.json` (project name, version, drops monorepo metadata, swaps `vexpo` workspace ref for the published version), runs `bun install`, and initializes a fresh git repo with `feat: initial commit`.
+
+After that, the project is standalone. The operational CLI (`vexpo`) is installed as a devDependency, so `bunx vexpo <subcommand>` resolves to the local pinned version. Setup commands aren't in `package.json`. They're one-shot CLI invocations, not runtime scripts.
+
+## Repo
+
+[github.com/ramonclaudio/vexpo](https://github.com/ramonclaudio/vexpo)

package/dist/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { existsSync } from 'fs';
+import { cp, rename, readFile, writeFile } from 'fs/promises';
+import { dirname, join, resolve, relative, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { execa } from 'execa';
+import kleur from 'kleur';
+import ora from 'ora';
+import prompts from 'prompts';
+
+// package.json
+var package_default = {
+  version: "0.1.0"};
+
+// src/index.ts
+var here = dirname(fileURLToPath(import.meta.url));
+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 `bunx vexpo lite` / `bunx vexpo full` prompt 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();
+  const name = await resolveName(argDir, flags.yes);
+  const target = resolve(process.cwd(), name);
+  if (existsSync(target)) {
+    console.error(kleur.red(`
+Target ${target} already exists. Pick a different name.`));
+    process.exit(1);
+  }
+  const pm = detectPackageManager();
+  const copySpin = ora(
+    `Copying template to ${kleur.cyan(relative(process.cwd(), target) || ".")}`
+  ).start();
+  try {
+    await cp(TEMPLATE_DIR, target, { recursive: true });
+    await restoreStrippedDotfiles(target);
+    await rewritePackage(target, name);
+    copySpin.succeed("Template copied");
+  } catch (err) {
+    copySpin.fail("Template copy failed");
+    throw err;
+  }
+  if (flags.install) {
+    const installSpin = ora(`Installing dependencies with ${kleur.cyan(pm)}`).start();
+    try {
+      await execa(pm, ["install"], { cwd: target, stdio: "ignore" });
+      installSpin.succeed(`Installed with ${pm}`);
+    } catch {
+      installSpin.warn(`Install skipped. Run ${kleur.cyan(`${pm} install`)} manually.`);
+    }
+  }
+  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");
+    } catch {
+      gitSpin.warn("Git init skipped");
+    }
+  }
+  nextSteps(target, flags, pm);
+}
+var NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var NAME_HINT = "lowercase letters, numbers, dashes; must start alphanumeric";
+function validateNameSegment(target) {
+  const segment = basename(target);
+  if (!NAME_RE.test(segment)) return { ok: false, reason: NAME_HINT };
+  return { ok: true };
+}
+async function resolveName(argDir, yes) {
+  if (argDir) {
+    const check = validateNameSegment(argDir);
+    if (!check.ok) {
+      console.error(kleur.red(`
+Invalid project directory '${argDir}'. ${check.reason}.`));
+      console.error(
+        kleur.gray(`Examples: my-app, my-cool-app, project1. Avoid spaces, unicode, npm scopes.`)
+      );
+      process.exit(1);
+    }
+    return argDir;
+  }
+  if (yes) return "my-vexpo-app";
+  const res = await prompts(
+    {
+      type: "text",
+      name: "name",
+      message: "Project directory",
+      initial: "my-vexpo-app",
+      validate: (v) => {
+        const check = validateNameSegment(v);
+        return check.ok ? true : check.reason;
+      }
+    },
+    { onCancel: () => process.exit(1) }
+  );
+  return res.name;
+}
+async function restoreStrippedDotfiles(target) {
+  const renames = [
+    ["_gitignore", ".gitignore"],
+    ["_env.example", ".env.example"],
+    ["_oxfmtrc.json", ".oxfmtrc.json"],
+    ["_oxlintrc.json", ".oxlintrc.json"],
+    ["_editorconfig", ".editorconfig"],
+    ["_gitattributes", ".gitattributes"],
+    ["_easignore", ".easignore"],
+    ["_fingerprintignore", ".fingerprintignore"],
+    ["_env.convex.local", ".env.convex.local"]
+  ];
+  for (const [from, to] of renames) {
+    const src = join(target, from);
+    if (existsSync(src)) await rename(src, join(target, to));
+  }
+}
+async function rewritePackage(target, requestedName) {
+  const pkgPath = join(target, "package.json");
+  const raw = await readFile(pkgPath, "utf8");
+  const parsed = JSON.parse(raw);
+  parsed.name = toPackageName(requestedName);
+  parsed.version = "0.0.0";
+  parsed.private = true;
+  delete parsed.author;
+  delete parsed.repository;
+  delete parsed.bugs;
+  delete parsed.homepage;
+  delete parsed.license;
+  delete parsed.publishConfig;
+  await writeFile(pkgPath, `${JSON.stringify(parsed, null, 2)}
+`);
+}
+function toPackageName(raw) {
+  const name = basename(raw).toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+  return name || "my-vexpo-app";
+}
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("bun")) return "bun";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("npm")) return "npm";
+  return "bun";
+}
+function intro() {
+  console.log();
+  console.log(kleur.bold().cyan("create-vexpo") + kleur.gray(` v${package_default.version}`));
+}
+function nextSteps(target, flags, pm) {
+  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`));
+  console.log(
+    kleur.gray(
+      `  bunx vexpo lite     ${kleur.dim("# dev mode: Convex + Better Auth, 60s to simulator")}`
+    )
+  );
+  console.log(
+    kleur.gray(
+      `  bunx vexpo full     ${kleur.dim("# real setup: TestFlight-ready (add --new if you're new)")}`
+    )
+  );
+  console.log();
+  console.log(kleur.bold("Then in two terminals:"));
+  console.log(kleur.gray(`  ${pm} run convex:dev   ${kleur.dim("# terminal 1")}`));
+  console.log(kleur.gray(`  ${pm} run ios          ${kleur.dim("# terminal 2")}`));
+  console.log();
+  console.log(kleur.gray("Docs: ") + kleur.cyan("https://github.com/ramonclaudio/vexpo"));
+  console.log();
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/templates/default/.eas/workflows/asc-events.yml

@@ -0,0 +1,84 @@
+name: App Store Connect events
+
+# Reacts to App Store Connect events using the `on.app_store_connect` trigger
+# (https://docs.expo.dev/eas/workflows/syntax/#onapp_store_connect). EAS
+# proxies ASC webhooks so we don't have to set up our own listener.
+#
+# Setup:
+#   1. Open EAS dashboard → Project settings → General → Connections
+#   2. Connect your App Store Connect app
+#   3. Paste your Slack incoming-webhook URL into each `webhook_url:` field
+#      below (or strip the slack jobs entirely if you don't use Slack).
+
+on:
+  app_store_connect:
+    app_version:
+      states:
+        - waiting_for_review
+        - in_review
+        - rejected
+        - accepted
+        - ready_for_distribution
+    build_upload:
+      states:
+        - complete
+        - failed
+    external_beta:
+      states:
+        - ready_for_beta_testing
+        - beta_approved
+        - beta_rejected
+    beta_feedback:
+      types:
+        - crash
+
+jobs:
+  # NOTE: EAS's `app_store_connect.*` workflow context only documents
+  # `app.id` and `build_upload.id`. Other event-specific properties (state
+  # values, beta-feedback details) aren't in the public context shape today.
+  # The `if:` guards below check whether the corresponding event key exists,
+  # so each notify only fires on the matching trigger. The message bodies
+  # link straight to App Store Connect rather than interpolating fields that
+  # may not resolve.
+
+  notify_review_state:
+    name: Slack notify on review state change
+    if: ${{ app_store_connect.app_version }}
+    type: slack
+    params:
+      # `webhook_url` only accepts hardcoded strings today; EAS env-stored
+      # interpolation for this field is upcoming. Paste your URL below.
+      webhook_url: https://hooks.slack.com/services/REPLACE/ME/HERE
+      message: |
+        App Store version state changed. App Store Connect → My Apps → App Store tab.
+        Workflow: ${{ workflow.url }}
+
+  notify_upload_state:
+    name: Slack notify on build upload
+    if: ${{ app_store_connect.build_upload }}
+    type: slack
+    params:
+      webhook_url: https://hooks.slack.com/services/REPLACE/ME/HERE
+      message: |
+        Build upload completed: ${{ app_store_connect.build_upload.id }}.
+        Workflow: ${{ workflow.url }}
+
+  notify_beta_state:
+    name: Slack notify on external beta state
+    if: ${{ app_store_connect.external_beta }}
+    type: slack
+    params:
+      webhook_url: https://hooks.slack.com/services/REPLACE/ME/HERE
+      message: |
+        External beta state changed. App Store Connect → TestFlight.
+        Workflow: ${{ workflow.url }}
+
+  notify_crash:
+    name: Slack notify on TestFlight crash
+    if: ${{ app_store_connect.beta_feedback }}
+    type: slack
+    params:
+      webhook_url: https://hooks.slack.com/services/REPLACE/ME/HERE
+      message: |
+        🔴 TestFlight crash reported. App Store Connect → TestFlight → Feedback.
+        Workflow: ${{ workflow.url }}

package/dist/templates/default/.eas/workflows/deploy-production.yml

@@ -0,0 +1,129 @@
+name: Deploy to production
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch: {}
+
+concurrency:
+  cancel_in_progress: true
+  group: ${{ workflow.filename }}-${{ github.ref }}
+
+defaults:
+  tools:
+    bun: latest
+
+jobs:
+  precheck:
+    name: Precheck
+    type: custom
+    runs_on: linux-medium
+    steps:
+      - uses: eas/checkout
+      - uses: eas/install_node_modules
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Lint
+        run: bun run lint
+      - name: Test
+        run: bun run test
+
+  deploy_convex:
+    name: Deploy Convex
+    needs: [precheck]
+    type: custom
+    runs_on: linux-medium
+    # `production` env pulls CONVEX_DEPLOY_KEY (a production deploy key, set
+    # at secret visibility) into the job. `convex deploy` is non-interactive
+    # whenever CONVEX_DEPLOY_KEY is present. no --yes / --auto-accept flag.
+    # https://docs.convex.dev/cli#deploy-convex-functions-to-production
+    # https://docs.convex.dev/cli/deploy-key-types
+    environment: production
+    steps:
+      - uses: eas/checkout
+      - uses: eas/install_node_modules
+      - name: Deploy Convex backend
+        run: bunx convex deploy
+
+  fingerprint:
+    name: Fingerprint
+    needs: [precheck]
+    type: fingerprint
+    environment: production
+
+  get_ios_build:
+    name: Check existing iOS build
+    needs: [fingerprint]
+    type: get-build
+    params:
+      platform: ios
+      fingerprint_hash: ${{ needs.fingerprint.outputs.ios_fingerprint_hash }}
+      profile: production
+
+  build_ios:
+    name: Build iOS
+    needs: [get_ios_build, deploy_convex]
+    if: ${{ !needs.get_ios_build.outputs.build_id }}
+    type: build
+    params:
+      platform: ios
+      profile: production
+
+  submit_ios:
+    name: Submit to App Store
+    needs: [build_ios]
+    type: submit
+    params:
+      build_id: ${{ needs.build_ios.outputs.build_id }}
+
+  update_ios:
+    name: OTA update
+    needs: [get_ios_build, deploy_convex]
+    if: ${{ needs.get_ios_build.outputs.build_id }}
+    type: update
+    environment: production
+    params:
+      platform: ios
+      branch: production
+
+  # Post-deploy notification with EAS Insights link. `update_ios` exposes
+  # `first_update_group_id` (https://docs.expo.dev/eas/workflows/pre-packaged-jobs/#update-outputs);
+  # we feed it into a Slack message that links to:
+  #   - the update group page (rollout %, runtime version, builds touched)
+  #   - the deployments dashboard (adoption curves, crash-free %, unique users)
+  #   - the channel insights page (filtered to production)
+  #
+  # `webhook_url` only accepts hardcoded strings today (env-stored webhooks
+  # are upcoming per https://docs.expo.dev/eas/workflows/pre-packaged-jobs/#slack);
+  # paste yours in `SLACK_WEBHOOK_URL` below and uncomment, or strip this job
+  # if you don't use Slack. The `print_insights` job prints `update:insights`
+  # JSON to workflow logs so you can audit adoption metrics directly.
+  print_insights:
+    name: Capture update:insights output
+    needs: [update_ios]
+    if: ${{ needs.update_ios.outputs.first_update_group_id }}
+    runs_on: linux-medium
+    steps:
+      - uses: eas/checkout
+      - uses: eas/install_node_modules
+      - name: Print insights JSON
+        run: |
+          GROUP="${{ needs.update_ios.outputs.first_update_group_id }}"
+          echo "Update group: $GROUP"
+          bunx eas-cli update:insights "$GROUP" --json --non-interactive || true
+
+  notify_update_published:
+    name: Notify Slack with insights link
+    needs: [update_ios]
+    if: ${{ needs.update_ios.outputs.first_update_group_id }}
+    type: slack
+    params:
+      # Replace with your Slack incoming-webhook URL. EAS does not yet
+      # support reading this from EAS env (see job comment above). interpolation
+      # of `${{ env.* }}` for `webhook_url` lands in a future EAS release.
+      webhook_url: https://hooks.slack.com/services/REPLACE/ME/HERE
+      message: |
+        :rocket: OTA update published to production.
+        Group: ${{ needs.update_ios.outputs.first_update_group_id }}
+        Workflow: ${{ workflow.url }}
+        Open the EAS dashboard for adoption %, crash-free %, and unique users.

package/dist/templates/default/.eas/workflows/development-builds.yml

@@ -0,0 +1,19 @@
+name: Development builds
+
+on:
+  workflow_dispatch: {}
+
+jobs:
+  ios_device:
+    name: iOS device
+    type: build
+    params:
+      platform: ios
+      profile: development
+
+  ios_simulator:
+    name: iOS simulator
+    type: build
+    params:
+      platform: ios
+      profile: development:simulator

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

@@ -0,0 +1,42 @@
+name: E2E tests
+
+# Builds an iOS Simulator binary and runs Maestro flows against it. Mirrors
+# the canonical EAS workflow at
+# https://docs.expo.dev/eas/workflows/examples/e2e-tests.
+#
+# Maestro flows live under .maestro/ at the repo root. The build profile
+# `development:simulator` already exists in eas.json. it produces a
+# .app bundle the Maestro runner can install on an iOS Simulator.
+#
+# `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}`.
+
+on:
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch: {}
+
+concurrency:
+  cancel_in_progress: true
+  group: ${{ workflow.filename }}-${{ github.ref }}
+
+jobs:
+  build_ios_simulator:
+    name: Build iOS Simulator
+    type: build
+    params:
+      platform: ios
+      profile: development:simulator
+
+  maestro:
+    name: Run Maestro flows
+    needs: [build_ios_simulator]
+    type: maestro
+    environment: development
+    env:
+      MAESTRO_APP_ID: ${{ env.EXPO_PUBLIC_APP_BUNDLE_ID }}
+    params:
+      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
+      flow_path: [".maestro"]
+      retries: 2

package/dist/templates/default/.eas/workflows/pr-preview.yml

@@ -0,0 +1,98 @@
+name: PR preview
+
+# Builds + auto-posts a comment on the PR with build/update IDs and QR codes
+# via the `github-comment` job. Mirrors the canonical EAS workflow pattern at
+# https://docs.expo.dev/eas/workflows/pre-packaged-jobs/#github-comment.
+#
+# Flow (canonical fingerprint-gated branch model):
+#   1. fingerprint → compute the iOS fingerprint for the PR's dev env.
+#   2. get_existing_build → check if any development:simulator build with
+#      that fingerprint already exists (returns build_id if so).
+#   3a. Path A (no compatible build): build a fresh dev-client simulator
+#       binary + publish a preview OTA to branch `pr-<n>` so the build
+#       picks it up on launch.
+#   3b. Path B (compatible build exists): publish a preview OTA only.
+#   4. github-comment → post the QR / build / update IDs.
+#
+# Either path publishes an update so a) the PR is always testable via a QR
+# scan and b) `pr-<n>` is a real EAS branch from the first commit, not the
+# second. Uses development:simulator (subscribed to the `development`
+# channel). vexpo doesn't ship a separate `preview` build profile.
+
+on:
+  pull_request:
+    branches: ["main"]
+
+concurrency:
+  cancel_in_progress: true
+  group: ${{ workflow.filename }}-${{ github.ref }}
+
+defaults:
+  tools:
+    bun: latest
+
+jobs:
+  precheck:
+    name: Precheck
+    type: custom
+    runs_on: linux-medium
+    steps:
+      - uses: eas/checkout
+      - uses: eas/install_node_modules
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Lint
+        run: bun run lint
+      - name: Test
+        run: bun run test
+
+  fingerprint:
+    name: Fingerprint
+    needs: [precheck]
+    type: fingerprint
+    environment: development
+
+  get_existing_build:
+    name: Find compatible build
+    needs: [fingerprint]
+    type: get-build
+    params:
+      platform: ios
+      fingerprint_hash: ${{ needs.fingerprint.outputs.ios_fingerprint_hash }}
+      profile: development:simulator
+      wait_for_in_progress: true
+
+  build_ios:
+    name: Build iOS Simulator (only if no compatible build exists)
+    needs: [get_existing_build]
+    if: ${{ !needs.get_existing_build.outputs.build_id }}
+    type: build
+    params:
+      platform: ios
+      profile: development:simulator
+
+  publish_update_new:
+    name: Publish preview update (new fingerprint path)
+    needs: [build_ios]
+    type: update
+    environment: development
+    params:
+      platform: ios
+      branch: pr-${{ github.event.pull_request.number }}
+
+  publish_update_existing:
+    name: Publish preview update (existing build path)
+    needs: [get_existing_build]
+    if: ${{ needs.get_existing_build.outputs.build_id }}
+    type: update
+    environment: development
+    params:
+      platform: ios
+      branch: pr-${{ github.event.pull_request.number }}
+
+  comment:
+    name: Post results to PR
+    after: [build_ios, publish_update_new, publish_update_existing]
+    type: github-comment
+    params:
+      message: "🚀 Preview ready. Scan the QR code or open the link to test."

package/dist/templates/default/.eas/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  cancel_in_progress: true
+  group: ${{ workflow.filename }}-${{ github.ref }}
+
+defaults:
+  tools:
+    bun: latest
+
+jobs:
+  precheck:
+    name: Precheck
+    type: custom
+    runs_on: linux-medium
+    steps:
+      - uses: eas/checkout
+      - uses: eas/install_node_modules
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Lint
+        run: bun run lint
+      - name: Test
+        run: bun run test
+
+  build_ios:
+    name: Build iOS
+    needs: [precheck]
+    type: build
+    params:
+      platform: ios
+      profile: production
+
+  submit_ios:
+    name: Submit to App Store
+    needs: [build_ios]
+    type: submit
+    params:
+      build_id: ${{ needs.build_ios.outputs.build_id }}
+      profile: production