@juangcarmona/lighthouse 0.6.0 → 0.7.0

package/assets/profiles/mobile-expo/README.md

@@ -0,0 +1,19 @@
+# Lighthouse Expo mobile profile
+
+Use this profile when Android or iOS is a real product requirement and the application will run as an Expo and React Native app.
+
+## Start here
+
+| Need | Read |
+| --- | --- |
+| New mobile application | [adoption](adoption.md) → [guardrails](guardrails.md) → [testing](testing.md) |
+| Add a native capability | [guardrails](guardrails.md) → [testing](testing.md) |
+| Export a web build | [adoption](adoption.md) → [testing](testing.md) |
+
+## Defaults
+
+Use Expo, React Native, Expo Router, strict TypeScript, TanStack Query and secure storage.
+
+Declare deep links, permissions, push notifications and native build targets before implementing a platform capability.
+
+Treat web export as an explicit selection with separate evidence. Do not make Expo a hidden layer on top of a React web profile.

package/assets/profiles/mobile-expo/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: lighthouse-mobile-expo
+description: Apply the Lighthouse Expo mobile profile when a repository selects mobile-expo.
+---
+
+# Lighthouse Expo mobile profile
+
+Read the mobile profile guide before changing an Expo adopter.
+
+Keep features aligned with product capabilities and use TanStack Query for server state. Keep credentials in secure storage and declare every permission and deep link.
+
+Treat Android and iOS behavior as native evidence. Add web export only when the product selects it and keep that evidence separate.
+
+Run Expo doctor, typecheck, tests and the selected emulator or device journey after a focused change.

package/assets/profiles/mobile-expo/adoption.md

@@ -0,0 +1,11 @@
+# Adopt the Lighthouse Expo mobile profile
+
+Select `mobile-expo` only when Android or iOS is a product requirement. Select `dotnet-backend` when the product also owns a Lighthouse backend.
+
+Set `application.shape` to `mobile` for a mobile-only project or `full-stack` for a mobile application with its backend, and include `expo` in `application.stacks`.
+
+Start with authentication, secure storage, one API call and one real interaction in an emulator or device.
+
+Choose web export deliberately and keep its browser evidence separate from native evidence.
+
+The mobile source, native configuration, permissions and signing policy become product-owned after adoption.

package/assets/profiles/mobile-expo/guardrails.md

@@ -0,0 +1,14 @@
+# Expo mobile guardrails
+
+| Guardrail | Level | Evidence | Failure |
+| --- | --- | --- | --- |
+| TypeScript and lint | Required | Deterministic static checks | The mobile slice stops before integration. |
+| Expo health | Required | Expo doctor and reproducible build | The selected native target is not ready. |
+| Secure storage | Required | Storage and logout test | Credentials remain unverified. |
+| Permissions and deep links | Required | Native configuration and lifecycle tests | The capability remains incomplete. |
+| Authentication and API | Required | Native integration evidence | The first mobile slice is not proven. |
+| Emulator or device journey | Required | Native test evidence | The selected platform remains unverified. |
+| Push notifications | Optional | Product-selected native evidence | No push behavior is assumed. |
+| Web export | Optional | Separate browser build and journey evidence | Native success does not imply web success. |
+
+Do not treat a web export as evidence for Android or iOS behavior.

package/assets/profiles/mobile-expo/testing.md

@@ -0,0 +1,13 @@
+# Expo mobile testing
+
+| Layer | Purpose | Evidence |
+| --- | --- | --- |
+| Static | TypeScript, lint and Expo configuration | CI output |
+| Unit and component | Feature and interaction behavior | Jest or Vitest with Testing Library |
+| Native integration | Secure storage, permissions, links and API boundary | Emulator or device evidence |
+| Lifecycle | Background, resume, logout, expiry and user change | Native journey evidence |
+| Web export | Selected web behavior | Separate browser evidence |
+
+The first vertical slice covers authentication, secure storage, one API call and one real interaction on the selected platform.
+
+Keep provider credentials out of fixtures and retain the device or emulator target with the evidence.

package/assets/profiles/mobile-maui/README.md

@@ -0,0 +1,19 @@
+# Lighthouse .NET MAUI mobile profile
+
+Use this profile when Android or iOS is a real product requirement and the application will run as a native .NET MAUI client.
+
+## Start here
+
+| Need | Read |
+| --- | --- |
+| New native application | [adoption](adoption.md) → [guardrails](guardrails.md) → [testing](testing.md) |
+| Add a device capability | [guardrails](guardrails.md) → [testing](testing.md) |
+| Prepare a release build | [adoption](adoption.md) → [guardrails](guardrails.md) |
+
+## Defaults
+
+Use C# and XAML with explicit lifecycle, secure storage, deep links, notifications, permissions and device capability boundaries.
+
+Use OIDC Authorization Code with PKCE and keep API contracts, permissions, pure business rules, errors, telemetry and visual principles aligned with the product's other clients.
+
+Do not reuse React components, browser cookies, web routing, persistence entities, DbContexts or internal handlers.

package/assets/profiles/mobile-maui/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: lighthouse-mobile-maui
+description: Apply the Lighthouse .NET MAUI mobile profile when a repository selects mobile-maui.
+---
+
+# Lighthouse .NET MAUI mobile profile
+
+Read the mobile profile guide before changing a .NET MAUI adopter.
+
+Keep platform capabilities behind explicit adapters and preserve the boundary between native lifecycle code and pure business rules.
+
+Use secure storage, OIDC Authorization Code with PKCE, declared permissions and tested deep links. Keep browser cookies and web routing outside the native client.
+
+Run locked restore, analyzers, unit tests and the selected emulator or device journey after a focused change.

package/assets/profiles/mobile-maui/adoption.md

@@ -0,0 +1,11 @@
+# Adopt the Lighthouse .NET MAUI mobile profile
+
+Select `mobile-maui` only when Android or iOS is a product requirement. Select `dotnet-backend` when the product also owns a Lighthouse backend.
+
+Set `application.shape` to `mobile` for a mobile-only project or `full-stack` for a mobile application with its backend, and include `maui` in `application.stacks`.
+
+Start with authentication, secure storage, one API call and one real interaction in an emulator or device.
+
+Select macOS or Windows targets only when the product requires them. Add packaging and signing only when they are in scope.
+
+The mobile source, native configuration, permissions and signing policy become product-owned after adoption.

package/assets/profiles/mobile-maui/guardrails.md

@@ -0,0 +1,13 @@
+# .NET MAUI mobile guardrails
+
+| Guardrail | Level | Evidence | Failure |
+| --- | --- | --- | --- |
+| Locked restore and build | Required | Deterministic restore and build per target | The selected native target is not reproducible. |
+| Analyzers and format | Required | Static checks and format verification | The mobile slice stops before integration. |
+| Secure storage and authentication | Required | OIDC, storage, logout and expiry tests | Credentials or session behavior remains unverified. |
+| Permissions and deep links | Required | Native configuration and lifecycle tests | The capability remains incomplete. |
+| Emulator or device journey | Required | Native functional evidence | The selected platform remains unverified. |
+| Notifications, camera and files | Optional | Product-selected native evidence | No device capability is assumed. |
+| Packaging and signing | Optional | Product-selected release evidence | No release signing is assumed. |
+
+Share contracts, permissions, pure rules, errors, telemetry and visual principles deliberately. Keep web routing, cookies, React components, persistence entities and internal backend handlers outside the client.

package/assets/profiles/mobile-maui/testing.md

@@ -0,0 +1,13 @@
+# .NET MAUI mobile testing
+
+| Layer | Purpose | Evidence |
+| --- | --- | --- |
+| Restore and build | Prove each selected target resolves and compiles | Locked CI output |
+| Unit | Exercise pure rules and client behavior | .NET test output |
+| Integration | Exercise API, authentication and secure storage boundaries | Approved test host or device evidence |
+| Lifecycle | Prove background, resume, logout, expiry and user change | Emulator or device journey |
+| Device capability | Prove selected permissions, links, notifications, camera or files | Target-specific evidence |
+
+The first vertical slice covers authentication, secure storage, one API call and one real interaction on the selected platform.
+
+Keep signing material and provider credentials outside fixtures. Retain the target platform and build configuration with the evidence.

package/assets/profiles/pwa-capability/README.md

@@ -0,0 +1,19 @@
+# Lighthouse PWA capability
+
+Use this capability when a React web application has a real installability or offline requirement.
+
+## Start here
+
+| Need | Read |
+| --- | --- |
+| Public installable web app | [adoption](adoption.md) → [guardrails](guardrails.md) |
+| Authenticated PWA | [adoption](adoption.md) → [offline policy](offline.md) |
+| Diagnose an update problem | [guardrails](guardrails.md) → [testing](testing.md) |
+
+## Defaults
+
+Declare the manifest, icons, service worker, asset cache, update strategy and offline behavior as part of the product surface.
+
+Cache assets separately from navigation and private data. Do not cache private APIs automatically and do not store tokens in browser storage.
+
+An authenticated PWA keeps the `web-bff` session boundary; installability does not change authentication ownership.

package/assets/profiles/pwa-capability/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: lighthouse-pwa
+description: Apply the Lighthouse PWA capability when a repository selects pwa-capability.
+---
+
+# Lighthouse PWA capability
+
+Read the PWA guide before changing an adopter's installability or offline behavior.
+
+Separate asset, navigation and private-data caching. Declare the bounded contexts that work offline and the actions that need the network.
+
+Keep authenticated sessions on the web BFF contract. Keep tokens out of browser storage and test logout, expiry and user changes.
+
+Run install, update, cache and browser evidence after a focused change. Treat a missing update or recovery test as an incomplete capability.

package/assets/profiles/pwa-capability/adoption.md

@@ -0,0 +1,9 @@
+# Adopt the Lighthouse PWA capability
+
+Select `pwa-capability` with `react-web-platform` when installability, asset caching or a declared offline journey is a product requirement.
+
+Choose the bounded contexts that work offline and record which actions remain online-only.
+
+Define the update and recovery behavior before enabling a service worker in production. Test a fresh install, an update, logout, session expiry and a user change.
+
+Keep the application source, manifest values, icons and service-worker implementation product-owned after adoption.

package/assets/profiles/pwa-capability/guardrails.md

@@ -0,0 +1,13 @@
+# PWA guardrails
+
+| Guardrail | Level | Evidence | Failure |
+| --- | --- | --- | --- |
+| Manifest and icons | Required | Deterministic build and installability check | The capability is not installable. |
+| Asset cache | Required | Service-worker inspection and browser test | The cache contract is incomplete. |
+| Update strategy | Required | Fresh-install and update journey | A stale application can remain active without a recovery path. |
+| Offline scope | Required | Declared bounded contexts and behavior review | Offline behavior remains ambiguous. |
+| Private API cache | Required | Static or review check | The capability stops until private-data caching is explicitly designed. |
+| Session lifecycle | Required for authenticated apps | Logout, expiry and user-change journeys | The session boundary remains unverified. |
+| Push | Optional | Product-selected permission and delivery evidence | No push behavior is assumed. |
+
+Do not enable offline-first behavior by convention. Make the offline boundary a product decision and keep it narrow.

package/assets/profiles/pwa-capability/offline.md

@@ -0,0 +1,11 @@
+# PWA offline policy
+
+Classify each bounded context as online-only, read-only offline or read-write offline before adding data caching.
+
+Keep assets, navigation and data caches separate so an update can invalidate one policy without changing the others.
+
+Read-only offline journeys need an explicit freshness rule and a visible stale state.
+
+Read-write offline journeys need conflict handling, replay rules, authentication recovery and evidence for a changed user.
+
+Private API responses remain online-only until the product and architecture define encryption, retention, invalidation and conflict behavior.

package/assets/profiles/pwa-capability/testing.md

@@ -0,0 +1,15 @@
+# PWA testing
+
+| Journey | Evidence |
+| --- | --- |
+| Fresh install | Manifest, icon and service-worker registration check |
+| Asset update | New revision replaces the cached revision |
+| Navigation offline | Declared navigation fallback behaves as designed |
+| Private data | No undeclared API response enters a cache |
+| Logout and expiry | Authenticated cache and session state are cleared or blocked |
+| User change | The next user cannot observe the previous user's data |
+| Push, when selected | Permission, delivery and revocation evidence |
+
+Run the journeys in a real browser context with a clean profile and a second revision of the application.
+
+A successful service-worker registration alone is not evidence that the update and data policies work.

package/assets/profiles/react-web-platform/README.md

@@ -0,0 +1,24 @@
+# Lighthouse React web profile
+
+Use this profile for React applications that need a predictable browser boundary, feature-oriented source and evidence for the journeys users rely on.
+
+## Start here
+
+| Need | Read |
+| --- | --- |
+| New web application | [structure](structure.md) → [guardrails](guardrails.md) → [testing](testing.md) |
+| Existing web application | [adoption](adoption.md) → [structure](structure.md) |
+| Implement a feature | [structure](structure.md) → [testing](testing.md) |
+| Diagnose a failed check | [guardrails](guardrails.md) |
+
+## Defaults
+
+Use React and strict TypeScript with thin routes, an app shell and feature slices aligned with bounded contexts and backend use cases.
+
+Use TanStack Query for server state and keep local state local; put filters, pagination and meaningful navigation state in the URL.
+
+Use explicit API contracts, visual-theme tokens, Testing Library, Vitest, Playwright and axe for the applicable surfaces.
+
+Add form, schema, mock or client-generation libraries only when a real feature requires them and the contract is stable.
+
+The profile does not create a runtime component library or turn shared folders into a technical-layer architecture.

package/assets/profiles/react-web-platform/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: lighthouse-react-web
+description: Apply the Lighthouse React web profile when a repository selects react-web-platform.
+---
+
+# Lighthouse React web profile
+
+Read the profile guide before changing a React adopter.
+
+Keep routes thin and organize behavior by feature and bounded context. Put screens, API calls, queries, mutations, components, types and tests beside the feature that owns them.
+
+Use TanStack Query for server state. Keep local UI state local and put filters, pagination and meaningful navigation state in the URL.
+
+Use explicit API contracts and render loading, empty, error, disabled and validation states for each interactive surface.
+
+Run the project's typecheck, lint, format, build, unit and browser checks after a focused change. Use axe evidence for critical surfaces.
+
+Application code, tests, dependencies and build policy become adopter-owned after creation. Do not overwrite them from the profile.

package/assets/profiles/react-web-platform/adoption.md

@@ -0,0 +1,17 @@
+# Adopt the Lighthouse React web profile
+
+## New application
+
+Select `react-web-platform` with `visual-theme`, set `application.shape` to `frontend` or `full-stack` and set `application.stacks` to include `react`.
+
+Run `lighthouse profiles --format json` before writing application code and keep the reported commands in the repository's normal verification loop.
+
+## Existing application
+
+Inventory routing, session, API contracts, server state, feature boundaries, interaction states, accessibility evidence, tests and build output before moving files.
+
+Map the existing implementation to the profile and record project-owned exceptions where a move would change behavior or ownership.
+
+Adopt one user journey first: session, authenticated screen, query, mutation, loading, empty, error and authentication failure.
+
+The application owns its source, tests, dependencies and build configuration after adoption; Lighthouse owns only the generated profile guidance and declared projections.

package/assets/profiles/react-web-platform/guardrails.md

@@ -0,0 +1,17 @@
+# React web guardrails
+
+| Guardrail | Level | Evidence | Failure |
+| --- | --- | --- | --- |
+| Strict TypeScript | Required | Deterministic typecheck | The profile is not ready for delivery. |
+| Lint and format | Required | Deterministic lint and format checks | The change stops before integration. |
+| Reproducible build | Required | Deterministic production build | The application cannot be released from this revision. |
+| Unit and component tests | Required | Deterministic Vitest and Testing Library checks | The affected slice needs repair. |
+| Critical browser journeys | Required | Playwright evidence | The journey remains unverified. |
+| Accessibility on critical surfaces | Required | axe evidence and human review where needed | The surface remains pending review. |
+| Import boundaries | Recommended | Static or architectural check | Record a project-owned exception with an owner and review date. |
+| Visual drift | Recommended | Visual evidence against the selected theme | Review the changed surface before accepting it. |
+| Performance budget | Optional | Project-selected budget check | Record why the budget is not applicable. |
+
+A public web application may call a public API directly when that decision is recorded; an authenticated web application selects `web-bff` by default.
+
+Do not store access or refresh tokens in localStorage, sessionStorage or IndexedDB. The BFF profile owns the authenticated browser session contract.

package/assets/profiles/react-web-platform/structure.md

@@ -0,0 +1,36 @@
+# React web structure
+
+Keep the repository source under `src/` and keep the primary architecture feature-oriented.
+
+```text
+src/
+  app/                         routes and application shell
+  features/
+    <bounded-context>/
+      <feature>/
+        screen/
+        api/
+        queries/
+        mutations/
+        components/
+        types/
+        tests/
+  shared/
+    http/
+    auth/
+    query/
+    errors/
+    telemetry/
+  api/
+  i18n/
+  design-system/
+tests/                          browser and cross-feature evidence
+```
+
+Routes compose screens and policy; they do not become a second application layer.
+
+Features follow bounded contexts and use cases. Extract shared code only when more than one feature has a real common contract.
+
+The API client exposes typed contracts and maps transport failures into application errors without leaking transport details into screens.
+
+The profile can run as a Vite SPA or another approved React framework when its output and verification commands remain explicit.

package/assets/profiles/react-web-platform/testing.md

@@ -0,0 +1,15 @@
+# React web testing
+
+Use a short feedback loop: typecheck and unit tests first, then integration and browser evidence for the behavior that crosses boundaries.
+
+| Layer | Purpose | Evidence |
+| --- | --- | --- |
+| Typecheck and lint | Catch static contract and style errors | CI output |
+| Unit and component | Exercise feature behavior and interaction states | Vitest and Testing Library |
+| Integration | Exercise API and BFF contracts where a boundary matters | Project-selected test harness |
+| Browser | Prove login, navigation, query, mutation and failure states | Playwright with catalogued evidence |
+| Accessibility | Catch critical semantic and keyboard regressions | axe plus human review when required |
+
+The first vertical slice covers session, an authenticated screen, a query, a mutation, loading, empty, error and authentication failure.
+
+Keep browser journeys few and valuable. Do not replace application tests with end-to-end tests or mock away the boundary being verified.

package/assets/profiles/web-bff/README.md

@@ -0,0 +1,22 @@
+# Lighthouse web BFF profile
+
+Use this profile for authenticated web applications that need a same-origin browser session and a server-side boundary for tokens and API calls.
+
+## Start here
+
+| Need | Read |
+| --- | --- |
+| New private web application | [adoption](adoption.md) → [security](security.md) → [testing](testing.md) |
+| Existing web application | [adoption](adoption.md) → [security](security.md) |
+| Implement a session change | [security](security.md) → [testing](testing.md) |
+| Diagnose an authentication failure | [security](security.md) |
+
+## Defaults
+
+Keep OAuth tokens outside browser JavaScript and use a Secure, HttpOnly session cookie with an explicit SameSite policy.
+
+Use Authorization Code with PKCE, CSRF protection, logout and revocation, destination and route allowlists, correlation IDs, ProblemDetails and rate limiting.
+
+Keep the BFF inside the ASP.NET Core host unless a product decision requires another deployment boundary.
+
+Treat direct browser-to-API access as a recorded exception for public or otherwise suitable APIs.

package/assets/profiles/web-bff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: lighthouse-web-bff
+description: Apply the Lighthouse web BFF profile when a repository selects web-bff for an authenticated web application.
+---
+
+# Lighthouse web BFF profile
+
+Read the profile guide before changing an authenticated web adopter.
+
+Keep OAuth tokens on the server side. Use Authorization Code with PKCE and a Secure, HttpOnly session cookie with an explicit SameSite policy.
+
+Validate origin and CSRF state, allow only declared destinations and routes, and expose stable ProblemDetails with correlation IDs.
+
+Implement logout, revocation, expiry and user switching as tested behavior. Keep rate limiting and observability at the BFF boundary.
+
+Run the session, API, browser and security checks after a focused change. Treat a missing security check as a repair action.

package/assets/profiles/web-bff/adoption.md

@@ -0,0 +1,9 @@
+# Adopt the Lighthouse web BFF profile
+
+Select `web-bff` with `react-web-platform` and `dotnet-backend` for an authenticated private web application.
+
+Set the session, identity provider, callback routes, logout route, allowed destinations and CSRF policy before exposing an authenticated screen.
+
+Start with one vertical slice: sign in, load the session, call one API query, submit one mutation, handle expiry and sign out.
+
+Existing authentication code remains product-owned. Map its behavior to the profile and record a narrow exception when migration would change a security boundary.

package/assets/profiles/web-bff/security.md

@@ -0,0 +1,16 @@
+# Web BFF security contract
+
+| Boundary | Contract | Required evidence |
+| --- | --- | --- |
+| Browser session | Secure, HttpOnly cookie with explicit SameSite policy | Cookie inspection and browser session test |
+| Authorization | Authorization Code with PKCE | Provider configuration and callback test |
+| CSRF | Origin and request-token policy for state-changing requests | Negative and positive mutation tests |
+| Destinations | Explicit allowlist for outbound targets and routes | Rejected destination test |
+| Proxying | Fixed routes and typed upstream calls | No arbitrary proxy path |
+| Logout | Session removal and provider revocation when supported | Logout and expired-session test |
+| Failure | Stable ProblemDetails and correlation ID | Error response and trace evidence |
+| Abuse | Rate limiting at the boundary | Configured limit and response test |
+
+Do not place access or refresh tokens in localStorage, sessionStorage or IndexedDB.
+
+The BFF may be hosted inside the ASP.NET Core application host. A separate service requires a product and architecture decision with its own deployment evidence.

package/assets/profiles/web-bff/testing.md

@@ -0,0 +1,14 @@
+# Web BFF testing
+
+Test the session boundary before the browser journey: callback, cookie flags, CSRF, allowlists, logout, expiry and user switching.
+
+| Layer | Purpose | Evidence |
+| --- | --- | --- |
+| Unit | Validate policy and mapping rules | Deterministic test output |
+| Integration | Exercise the BFF and upstream contract | Real host or approved provider fixture |
+| Browser | Prove sign in, authenticated query, mutation and sign out | Playwright evidence |
+| Security review | Confirm storage, routes and failure handling | axe is complementary; security review remains explicit |
+
+The first vertical slice must fail closed when the session is absent, expired or assigned to another user.
+
+Keep provider credentials out of fixtures. Use a deterministic identity or approved test provider that exercises the same cookie and callback boundaries.