Prueba mínima de GUI

npm run dev                # http://127.0.0.1:5173/en
npm run preview            # Production build on local Workers, port 4173
npm run dev:change        # The check, in seconds (the flow's first step)

Un único scaffold para local y CloudflareCopy Anchor Link

wrangler.jsonc es la fuente de verdad para la entrada del Worker, los flags de compatibilidad, los bindings y la observabilidad. Vite genera dist/server/wrangler.json y .wrangler/deploy/config.json; no edites a mano ni hagas commit de ninguno de los dos archivos generados. Tanto la preview local como el deployment de Wrangler consumen la build de producción generada. El desarrollo usa el mismo código fuente del Worker y el mismo runtime de Cloudflare con hot reload.

El flujo no ejecuta toda la suite contra un deployment: los deploys terminan con el smoke en vivo, y GitHub ejecuta la suite después de cada landing. Para ejecutarla toda contra una URL desplegada a propósito, una persona lo indica en una terminal (el comando se niega sin ello, y el guard se niega a hacerlo desde un agente):

REMY_FLOW=hand npm run test -- remote https://your-worker.your-subdomain.workers.dev

La URL debe ser un origin, sin path ni query. Las comprobaciones que necesitan una persona nueva leen su código de la captura de correo local, así que solo se ejecutan contra el destino local. El resto le preguntan al Worker qué entorno es (/healthz) y esperan lo que la tabla les dé: contra staging las personas precargadas están presentes y una pulsación inicia sesión como una de ellas; contra producción nada de eso existe. La tarea de pruebas remotas también puede apuntar a una preview local ya en ejecución para comprobar la ruta del servidor externo.

Los comandos son los del paquete (remy), controlados por el remy.config.ts de este proyecto (los origins, los puertos); los propios de este repositorio son sus scripts de package.json (local, generate, release-checks, test:consumers; la línea de comandos). La configuración de Playwright es el playwrightConfig() del paquete.

Existe una única configuración de Worker con un entorno con nombre, staging (env.staging en wrangler.jsonc): el mismo código como su propio Worker, con sus propias bases de datos y secreto. Un entorno con nombre se selecciona con CLOUDFLARE_ENV en tiempo de build, tal como exige la integración de Cloudflare con Vite; remy cloudflare staging (que dev:land ejecuta) hace eso y luego todo lo que hace el deploy de producción. Mantén la implementación compartida; varía solo los identificadores de recursos, los secretos y demás valores de entorno. Los bindings, las vars y los secretos requeridos no los hereda un entorno con nombre: cada uno se declara de nuevo ahí. No dupliques la aplicación ni uses bindings remotos para el desarrollo local habitual. Los secretos locales permanecen en .dev.vars, que está ignorado; los secretos desplegados se gestionan a través de Cloudflare. Los datos locales no se suben con el deployment.

Dos tipos de páginaCopy Anchor Link

packages/ui/src/paths.js es la única lista de páginas y dice qué promete cada tipo; los dos nunca se mezclan.

• Las páginas de sitio (sitePaths: el home y los formatos) son para Google: completas en el HTML del servidor sin JavaScript, indexadas, en el sitemap con alternativas hreflang, y evaluadas por el nivel 2. Su marco es SiteShell en shell.tsx, construido con partes estáticas de shadcn.
• Las páginas de app (appPaths, bajo /app) necesitan JavaScript, llevan noindex (añadido por pageHead) y quedan fuera del sitemap. Su marco es AppShell en app-shell.tsx, el bloque sidebar-16 de shadcn, gestionado en blocks/sidebar-16.

Los docs no son páginas de esta app: son el Worker de docs (docs/, Fumadocs), con la guía en /docs, estos docs para desarrolladores en /dev y la referencia de la API en /reference, cada uno con búsqueda y Ask AI (escribir docs). El encabezado de la app enlaza allí, y sus antiguas direcciones /<locale>/docs/... redirigen allí de forma permanente.

El selector de idioma sigue el tipo: las páginas de sitio usan LanguageSwitcher, enlaces simples que no necesitan JavaScript; las páginas de app usan LanguageMenu, el DropdownMenu de shadcn que llama a setLocale de Paraglide (ambos en language.tsx).

Qué está implementadoCopy Anchor Link

Cada página existe en cada locale (13 prefijos como /en, /ar, /ja; las páginas de docs solo en inglés); la tabla las nombra sin él.

Las páginas localizadas nunca redirigen. Cuando el idioma preferido del visitante difiere del de la página, una sugerencia descartable ofrece esa versión; elegirla o descartarla se recuerda en la cookie PARAGLIDE_LOCALE de Paraglide, sobre la que solo actúan las URLs de entrada. La detección de locale, la cookie, la localización de URLs y la redirección son las propias estrategias y el middleware de Paraglide (packages/ui/paraglide.mjs contiene la única configuración del compilador), integrados como la integración oficial de Paraglide con TanStack Start: el middleware envuelve la entrada del Worker, y el rewrite del router elimina el locale antes de hacer el matching y lo añade a cada enlace, de modo que las rutas no llevan segmento de locale.

TanStack Start se ejecuta a través del plugin de Vite de Cloudflare (vite.config.ts). Todas las rutas se renderizan en servidor excepto la demo. Los enlaces dentro de la app precargan el código y los datos de su ruta según la intención; los cambios de idioma en las páginas de sitio son navegaciones completas.

shadcn, de fábricaCopy Anchor Link

Los componentes y el tema son lo que escribe la CLI de shadcn, en el diseño de monorepo de shadcn: el components.json de esta app dirige shadcn add hacia el paquete (packages/ui/components.json), y packages/ui/src/styles/globals.css también lo escribe la CLI. Nadie edita ninguno de los dos a mano; los scripts de package.json son la única forma en que cambian:

npm run ui:components       # Re-add every shadcn component (extend the list there to add one)
npm run ui:theme            # Rewrite globals.css with shadcn's default theme
npm run ui:blocks           # Diff each owned block against upstream, in place
npm run ui:verify           # Re-run both and fail on any difference (runs before every release)
npm run packages -- pack    # Produce the package tarballs locally

Los bloques son copias propias, tal como shadcn pretende; el README de sidebar-16 explica qué se cambió. El alias components del paquete (@joeblew999/remy-ui/blocks) es donde shadcn escribe los archivos propios de un bloque cuando se ejecuta desde el paquete (shadcn add <block> -c packages/ui): blocks/<name>/components. Así, ui:blocks los compara en su sitio y los cambios de upstream se fusionan a mano.

Las fuentes viven en packages/ui/src/fonts.css, importado después de globals.css (ver src/styles.css); el archivo explica sus reglas. fontaine en vite.config.ts genera las fuentes de respaldo ajustadas en tamaño que nombra. publicPageChecks falla ante cualquier familia nombrada que no esté cargada.

Qué versión está desplegadaCopy Anchor Link

Nada registra qué está desplegado: cada deployment dice qué es cuando se le pregunta, de modo que la respuesta no puede quedar desactualizada (el diseño es de remy-sport, cuyo registro versionado de deployments estuvo equivocado durante semanas).

• El sello de build. remyApp() y remyDocs() lo calculan una vez por build a partir de las fuentes: el paquete de la app, el commit, un hash corto de cualquier cambio sin confirmar, y la versión instalada de cada paquete de la plataforma (build: { packages: [...] } en remyApp() enumera más). El mismo checkout produce el mismo sello; no incluye la hora de build, así que un bundle solo cambia cuando cambia su código.
• /healthz, en cada Worker construido sobre el paquete, responde con él: service, environment (lo que el Worker declara; producción cuando no declara ninguno), release y deployedAt (la versión de Cloudflare y cuándo se le asignó) y build. No nombra a nadie, y cualquier origin puede leerlo.
• BuildStamp (@joeblew999/remy-ui/versions) está en el pie del marco de la app, así que toda página de app de toda app lo tiene: el entorno salvo que sea producción, el nombre del producto, el commit. La página lleva el sello con el que se construyó; cuando su deployment responde con otro, la página es una pestaña que quedó abierta a través de un deploy, y el sello ofrece el reload. Nunca se recarga por sí sola.
• Versions, para una página de ajustes o acerca de: esta app, su Worker de docs (docs en defineRemyApp) y los deployments que la app enumera ahí (staging junto a producción, un servicio al que llama), cada uno respondiendo por sí mismo, y luego los paquetes con los que se hizo este build. La página de Settings de remy-auth lo muestra, con su producción y su staging.
• npm run dev:status (y npx remy cloudflare versions) imprime una fila por deployment (los origins de remy.config.ts, o los origins dados), situando cada commit respecto a este checkout: = HEAD, 3 behind HEAD. Úsalo antes de decir qué está en producción.

Los conjuntos de comprobaciones compartidos lo demuestran en cada app: /healthz nombra el commit de este checkout en una ejecución local (un sello que quedó de un build anterior falla), y el marco ofrece el reload solo cuando el deployment ha avanzado.

El nombre del productoCopy Anchor Link

Remy es el nombre de este prototipo. Un proyecto construido sobre el mismo código tiene el suyo propio, y lo escribe una sola vez:

// docs/docs.config.ts: los docs lo dicen, y la app lo toma de aquí
const product = 'Harbor';
export const docsConfig = defineDocsConfig({ product, ... });

// src/remy-app.tsx
export const remyApp = defineRemyApp({ brand: docsConfig.product, ... });

Una app sin docs escribe brand directamente. Todo lo que una persona lee toma el nombre de ahí: el marco, el título de cada página, los datos estructurados de la página de inicio, y todo mensaje que diga el nombre, que lo recibe como parámetro:

m.home_title({ product: useRemyApp().brand }, { locale })                       // en una página
pageHead({ ..., description: (locale, product) => m.home_description({ product }, { locale }) })   // en un head
codeMail({ otp, product }, locale)                                              // el correo de inicio de sesión

Un mensaje que nombra al producto se escribe con {product}, nunca con un nombre fijo, de modo que los tipos de Paraglide rechazan a quien lo omita. La página de Settings de remy-auth muestra dónde se usa el nombre, y cómo se leería cada lugar con otro nombre.

Lo que no es el nombre del producto, y permanece: los paquetes (@joeblew999/remy-ui), la skill remy, los nombres de tareas, el nombre de servicio de un Worker y el nombre de un servidor MCP. Son identificadores que ve un desarrollador.

Comprobaciones: el título de cada página termina con el nombre de la app, y una app con otro nombre nunca muestra «Remy» (productNameChecks, en el conjunto compartido de cada app; el fixture consumidor, llamado «My app», es donde esto se nota); el catálogo de la plataforma no nombra a ningún producto (tests/product.spec.ts).

Estructura y reutilizaciónCopy Anchor Link

• src/routes/: rutas de archivo de TanStack (loaders, head, renderizado por ruta) que renderizan las páginas del paquete, más las filas de formatos adicionales de esta app (src/formats-extras.tsx), mientras que robots.txt y sitemap.xml (la parte seo-routes) y /csp-report (app-routes) son las rutas de servidor del paquete, montadas junto a ellas; src/routeTree.gen.ts lo genera el plugin del router durante el dev y el build, y se versiona.
• src/server.ts: entrada del Worker a través del localizedWorker del paquete (IDs de petición, logs de estado estructurados, /healthz, el middleware de Paraglide, redirecciones de entrada). Start recibe la petición original, así que las funciones de servidor leen la geolocalización de Cloudflare a partir de las propiedades cf de la petición en un módulo exclusivo de servidor bajo la protección de imports de Start (packages/showcase/src/parts/deferred-place/place.server.ts, la parte deferred-place del showcase). El wrapper pasa su ID de petición hacia dentro como X-Request-ID; el middleware de petición de Start lo expone como context.requestId, y un middleware de función registra una línea server_fn por cada llamada (el start del paquete, registrado en src/start.ts). Ahí mismo, un segundo middleware de petición genera el nonce de CSP por petición que el router compartido (router) entrega a TanStack Router, y la ruta de servidor /csp-report del paquete (app-routes) registra los reportes de la política (cabeceras de seguridad). El nombre del servicio tiene un único hogar, src/service.ts.
• src/api/: la implementación del contrato (router.ts, tras el guard; sin imports de Workers para que las comprobaciones puedan cargarlo en Node), el contexto de cada llamada, con la sesión de quien llama (context.server.ts), y el cliente isomórfico con sus utilidades de TanStack Query (client.ts). El contrato es packages/contract/; el mecanismo compartido son las exportaciones api/* del paquete; el plan de contratos es dueño del diseño.
• src/auth/: Better Auth en este Worker (el plan de autenticación): sus opciones, compartidas por el Worker y la CLI (options.ts), la instancia construida en el primer uso a partir del binding D1 (auth.server.ts), la configuración de la CLI (cli.ts), la tabla de entorno (environment.ts), las personas precargadas (seed.ts, people.server.ts), el envío de correo y el correo del código (mail.server.ts, code-mail.ts), la regla sobre los campos que una persona puede escribir (fields.ts), la función de servidor de la cuenta (account.ts) y el formulario de inicio de sesión, su selector y el cliente de navegador de Better Auth (sign-in.tsx, client.ts). migrations/ contiene las migraciones numeradas de D1 (tareas).
• src/notes/: la demo de notas, que usa el motor de relaciones como lo haría cualquier app: sus datos en su propia D1 (DEMO_DB, migrations-demo/; ahí una persona es solo un ID de cuenta) a través de store.ts, la página (page.tsx) y la función de servidor que su loader consulta (state.ts). El vocabulario y las formas son los del contrato (packages/contract/src/notes.ts).
• src/router.tsx: el remyRouter del paquete, un router y un cliente de TanStack Query nuevos por petición, con la integración SSR de Query. src/routes/__root.tsx es el remyRoot del paquete con la configuración de esta app; TanStack Devtools (paneles de Router y Query) se pasa ahí, en el propio archivo de la app, porque su plugin de Vite devtools() lo elimina de las builds de producción solo fuera de node_modules; la comprobación de frontera de build demuestra que ni devtools ni código exclusivo de servidor llegan al navegador.
• src/parts.json: las partes del paquete que usa esta app, una por línea (@joeblew999/remy-showcase/time-zones, deferred-place y status-card del showcase, y seo-routes de la plataforma); remyParts() en vite.config.ts monta sus rutas y partChecks() en tests/gui.spec.ts ejecuta sus comprobaciones.
• packages/ui/: todo lo que comparten ambas apps; su README enumera las exportaciones.
• tests/: las comprobaciones compartidas del paquete (@joeblew999/remy-ui/checks, el @joeblew999/remy-showcase/*.checks del showcase) más las comprobaciones que solo posee este repositorio (catálogos, renderizados concurrentes en servidor, hidratación, sus filas de formatos adicionales); lighthouse.spec.ts y performance.spec.ts son de nivel 2.

El locale se pasa explícitamente a las funciones de mensaje compiladas; las peticiones concurrentes no comparten estado mutable de locale. Los catálogos son los locales en settings.json; todos salvo inglés y español fueron escritos por un agente y no están revisados. La dirección, los endónimos, las fechas, los números, la moneda y los plurales siguen las decisiones registradas en el plan de GUI.

El consumidor real del paquete es remy-auth-app, que instala el paquete publicado y ejecuta sus comprobaciones sobre páginas prerenderizadas, mientras que esta app las ejecuta sobre páginas renderizadas en servidor.

Evidencia y límitesCopy Anchor Link

Dos niveles: el nivel 1 es cada comprobación nuestra en cada idioma (npm run test -- every); el nivel 2 es el de Google (npm run test -- google, npm run test -- cwv). Lo que cubren las comprobaciones son las propias comprobaciones: tests/ y el @joeblew999/remy-ui/checks del paquete (el título de cada comprobación dice qué demuestra); los pasos del flujo que las ejecutan están en cómo trabajamos. En resumen: cada página en cada idioma sin JavaScript (idioma, dirección, metadatos, enlaces), catálogos y plurales, los valores de formatos frente a Intl, las redirecciones de entrada y la sugerencia de idioma, la hidratación, el formulario de demo y la API, los estados HTTP, el sitemap y hreflang, las cabeceras de seguridad y el nonce de CSP, las pantallas estrechas, y las páginas de docs, búsqueda y ask.

El nivel de Google cubre solo las páginas de sitio (las páginas de app son noindex por diseño): Lighthouse audita /en (móvil y escritorio), /es, /ar y /en/formats (tests/lighthouse.spec.ts); Core Web Vitals, a partir del paquete lighthouse fijado de Google, evalúan /en (móvil y escritorio) y /en/formats (tests/performance.spec.ts) frente a los umbrales buenos de Google (LCP 2.5 s, CLS 0.1, TBT 200 ms, Performance de al menos 0.9), en un Worker de Cloudflare desechable (npm run test -- cwv), no en localhost.

Límites: todavía no hay organizaciones, tokens OAuth ni inicio de sesión entre apps, así que solo las páginas propias de remy-auth saben quién ha iniciado sesión (el plan de autenticación). El sitio se sirve desde su dirección de workers.dev (DEPLOY_ORIGIN); el origin público de producción y Search Console son decisiones del propietario (now).

Avisos de herramientas conocidos: Node puede imprimir el aviso experimental de localStorage de Chrome DevTools; npm informa de scripts de instalación upstream no aprobados; la comprobación de paquete aislado de Vite puede informar de que las directivas use client de Base UI se ignoran en un bundle de cliente plano. Estos avisos no cambian los comportamientos probados.