feat: wire web bootstrap to Convex runtime

[BASIC-BIT]

Summary

• mount a minimal Convex provider baseline in the Next.js app and surface a live homepage runtime card backed by health:status
• read the local Convex URL from repo bootstrap output so the web app can prove the stack works end to end during local development
• document the new web-to-Convex local flow and harden web typecheck around the current Next 16 generated type stub gap

Testing

• pnpm lint:web
• pnpm typecheck:web
• pnpm build:web
• verified the homepage status card reaches local Convex and shows ok in a browser smoke check

[greptile-apps]

Greptile Summary

This PR mounts a minimal Convex provider in the Next.js app and wires the homepage to the health:status query, completing the initial web-to-Convex runtime path. A new scripts/run-convex-local.mjs helper mirrors CONVEX_URL from the repo-root .env.local into apps/web/.env.local as NEXT_PUBLIC_CONVEX_URL, keeping the client-side wiring aligned with Next.js naming conventions. A StatusCardErrorBoundary with a retry action and useQuery-based live polling round out the homepage status card.

• ConvexClientProvider.tsx: Client created once at module scope from NEXT_PUBLIC_CONVEX_URL; safely falls back to rendering children without a provider when the env var is absent.
• backend-status-card.tsx: Uses useQuery(api.health.status, {}) against the mounted provider, wrapped in an error boundary with a reset path; shows a static fallback when the URL is not configured.
• scripts/run-convex-local.mjs: syncPublicConvexUrl() now strips quotes/inline comments from the parsed URL, preserves all existing .env.local keys on write, uses fs.watch on the target file (with directory-watch fallback), and is wrapped in try-catch at every call site.
• apps/web/tsconfig.json: Adds baseUrl: "." and the **/*.mts include glob; no path alias was added for the convex/_generated import used in backend-status-card.tsx.
• ensure-next-type-stubs.mjs: Creates the missing .next/types/cache-life.d.ts stub so tsc does not fail on clean checkouts with Next.js 16.
• apps/web/package.json: Restores the full typecheck chain (next typegen → stub script → tsc) and adds convex@^1.32.0.

Confidence Score: 3/5

• Functionally correct for the happy path, but two residual issues from earlier review rounds persist in the final HEAD: the syncPublicConvexUrl trailing-newline artifact on URL-change writes, and the unaliased four-level relative import to convex/_generated/api.
• The core runtime wiring (ConvexProvider mount, useQuery, error boundary with retry, env-var mirroring) is implemented correctly and the prior review concerns around security, polling cost, error handling, and type safety were substantively addressed across the follow-up commits. However, syncPublicConvexUrl's merge path still produces a spurious blank line when apps/web/.env.local ends with a newline and the URL changes — a write-path bug that was claimed fixed in 61d7a77 but is absent from the current code. Similarly, the tsconfig path alias claimed in 61d7a77 for the convex/_generated import was not applied; ../../../../convex/_generated/api is still a raw four-level relative path with no alias entry in paths. Both issues are minor in isolation but represent gaps between claimed and actual state.
• scripts/run-convex-local.mjs (syncPublicConvexUrl merge path) and apps/web/tsconfig.json + apps/web/src/app/backend-status-card.tsx (missing convex/_generated path alias)

Important Files Changed

Filename	Overview
apps/web/src/app/ConvexClientProvider.tsx	Minimal Convex provider wrapper created at module scope to avoid recreating the client; conditionally renders children without the provider when NEXT_PUBLIC_CONVEX_URL is unset.
apps/web/src/app/backend-status-card.tsx	Status card uses useQuery against the mounted Convex provider with an error boundary (including retry), and references the generated api.health.status type. The deep four-level relative import to convex/_generated/api remains without a corresponding tsconfig path alias.
scripts/run-convex-local.mjs	Adds syncPublicConvexUrl() to mirror NEXT_PUBLIC_CONVEX_URL into apps/web/.env.local, with file-first fs.watch fallback to directory watch, error handling at every call site, and URL parsing that strips quotes and inline comments. A split trailing-artifact bug means a file ending with \n receives a spurious blank line before the appended URL on each URL-change write.
apps/web/tsconfig.json	Adds baseUrl: "." and **/*.mts include glob; no path alias for convex/_generated so the four-level relative import in backend-status-card.tsx is unaliased. Formatting changes only otherwise.
apps/web/scripts/ensure-next-type-stubs.mjs	New helper that idempotently creates .next/types/cache-life.d.ts to fill a Next.js 16 generated-type gap; wired into the typecheck script chain so tsc doesn't fail on a clean checkout.
apps/web/package.json	Adds convex@^1.32.0 dependency and restores the full typecheck chain (next typegen + stub script + tsc) that was previously simplified, keeping the workspace script self-contained.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Bootstrap as run-convex-local.mjs
    participant RepoEnv as .env.local (repo root)
    participant WebEnv as apps/web/.env.local
    participant ConvexDev as Convex Dev Server
    participant Browser as Browser
    participant Provider as ConvexClientProvider
    participant Card as BackendStatusCard / useQuery
    participant Backend as convex/health.ts

    Dev->>Bootstrap: pnpm dev:backend:local
    Bootstrap->>ConvexDev: spawn convex dev --local
    ConvexDev-->>RepoEnv: write CONVEX_URL=http://localhost:…
    Bootstrap->>Bootstrap: syncPublicConvexUrl() (initial)
    Bootstrap->>WebEnv: write NEXT_PUBLIC_CONVEX_URL=http://localhost:…
    Bootstrap->>RepoEnv: fs.watch (file watcher)
    RepoEnv-->>Bootstrap: change event
    Bootstrap->>WebEnv: syncPublicConvexUrl() (on change)

    Dev->>Browser: pnpm dev:web → open homepage
    Browser->>Provider: mount ConvexClientProvider
    Provider->>Provider: new ConvexReactClient(NEXT_PUBLIC_CONVEX_URL)
    Provider->>ConvexDev: open WebSocket
    Browser->>Card: render BackendStatusCard
    Card->>Provider: useQuery(api.health.status, {})
    Provider->>Backend: subscribe health:status
    Backend-->>Provider: { status: "ok", … }
    Provider-->>Card: result
    Card-->>Browser: display live status

Loading

_{Reviews (10): Last reviewed commit: "fix: reduce Convex bootstrap path brittl..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6d140b19e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".