diff --git a/AGENTS.md b/AGENTS.md index 14a7396f..a1e01410 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,9 +4,70 @@ Owns the Angular public website, operator dashboard and embeddable authenticatio Start with the canonical [work state](../user-proxy/docs/WORK-STATE.md), [architecture](../user-proxy/docs/ARCHITECTURE.md), [capabilities](../user-proxy/docs/CAPABILITIES.md), [development](../user-proxy/docs/DEVELOPMENT.md), [security](../user-proxy/docs/SECURITY-OPERATIONS.md) and [design](../user-proxy/docs/DESIGN.md). Preserve existing README contribution rules and DESIGNGUIDE.md. Read widget integration/event guides before changing the custom element contract. -- Branch workflow: use `production` as the frontend base and PR target. Before pushing a feature branch or opening its PR, fetch and merge the latest `origin/production` into that feature branch. Keep release branches unchanged until PR review. -- Inspect status/diff; preserve unrelated changes. New application code uses TypeScript and existing standalone Angular patterns. Use Angular CLI scaffolding when practical; never change architecture solely to satisfy scaffolding. -- Install from lock using `npm ci --ignore-scripts --legacy-peer-deps`; generate ignored env modules with `node tools/set-env`. Review environment base URLs before starting: local config defaults to a remote test API. -- Run `node --test tools/tests/*.test.cjs`, affected builds and `git diff --check`. Existing Nx/Jest targets have known gaps: report exact commands and limitations in canonical work state. -- Keep error, denied, empty and loading states distinct; provide retry. Never render request data as HTML or log/store tokens. Client visibility does not replace server authorization. -- Update the single backend-owned capability matrix and work state alongside changes. Product/architecture guidance is linked, not duplicated here. Public claims require evidence; do not invent SLAs, guarantees or future functional controls. +## Commands + +| Task | Command | +|---|---| +| Install | `npm ci --legacy-peer-deps` (Node 20; peer deps conflict without the flag) | +| Env setup | `cp .env.example .env` and fill in the values. `tools/set-env.js` generates the git-ignored env-variables.ts for each app ([docs/environment.md](docs/environment.md)) | +| Run dashboard | `npm start` (port 4200) | +| Run widget alone | `npm run start:proxy-auth` (also port 4200) | +| Build widget into dashboard assets | `npm run build:proxy-auth` | +| Full build | `npm run build:test`, `npm run build:stage` or `npm run build:prod`. Plain `npm run build` mixes a prod widget with a local dashboard | +| Format | `npm run format:code`. Prettier also runs on pre-commit through husky and lint-staged | + +`npm test` and `npm run lint` are not reliable at this commit: there is no test target on the dashboard, and `nx workspace-lint` is gone in Nx 21. Check a change by building the affected app: `npx nx build 36-blocks` or `npx nx build 36-blocks-widget` (run `node tools/set-env` first). The CI "Build check" workflow fails on every PR today because it never runs `set-env`, so a red check there says nothing about your change ([docs/environment.md](docs/environment.md#ci-githubworkflowsmainyml-build-check)). + +## Read before you change + +- Anything → [docs/architecture.md](docs/architecture.md), then [docs/conventions.md](docs/conventions.md); why things are shaped this way → [docs/decisions.md](docs/decisions.md) +- The widget's public API, events or build → [docs/modules/widget-embed.md](docs/modules/widget-embed.md) and [docs/api.md](docs/api.md#widget-public-api-host-page--widget) +- Widget login, register or OTP → [docs/modules/widget-auth.md](docs/modules/widget-auth.md), [docs/flows/widget-verification.md](docs/flows/widget-verification.md) +- Widget account screens → [docs/modules/widget-account.md](docs/modules/widget-account.md) +- Dashboard login, token or guards → [docs/modules/app-shell.md](docs/modules/app-shell.md), [docs/flows/dashboard-login.md](docs/flows/dashboard-login.md) +- Blocks (features) wizard, OAuth clients, client secrets, redirect response mode → [docs/modules/panel-features.md](docs/modules/panel-features.md), [docs/flows/feature-configuration.md](docs/flows/feature-configuration.md) +- Users, logs, billing, dashboard, layout → [docs/modules/panel-ops.md](docs/modules/panel-ops.md) +- `libs/**`, HTTP, the interceptor → [docs/modules/shared-libs.md](docs/modules/shared-libs.md) +- Routes, state, components, styling → [docs/ui/](docs/README.md#ui) +- A common change (page, backend call, block tab, widget key or screen, env value, lib, release) → [docs/recipes.md](docs/recipes.md) + +## Rules + +1. Never rename or remove any part of the widget's public contract: + - `window.initVerification` and the `proxy-auth` tag + - `window.__proxyAuth` and the `openAddUserDialog` event + - the `userProxyContainer` id and the assets/proxy-auth/proxy-auth.js path + - any value in `libs/constant/src/verification/verification.ts` + + Customer sites depend on all of these. Add new values instead ([docs/api.md](docs/api.md)). +2. No dynamic `import()` in `apps/36-blocks-widget`. `build-elements.js` leaves the `chunk-*` file it creates out of the single-file bundle, so the bundle breaks on host pages. +3. A new `initVerification` config key that must not be sent to the backend goes into `RESERVED_KEYS` in `apps/36-blocks-widget/src/app/init-verification.ts`. Every other key is POSTed as `otherData` ([recipe](docs/recipes.md#add-an-initverification-config-key)). +4. Put widget CSS in component styles. `apps/36-blocks-widget/src/styles.scss` is also injected into the host page's ``. Build overlays with `WidgetPortalService` / `WidgetDialogService`. +5. Set and clear the dashboard token only through `AuthService.setTokenSync` / `clearTokenSync`. They keep the `authToken` cookie and the in-memory `IToken` in sync. Guards read both, HttpWrapper reads memory, and ErrorInterceptor reads only the cookie ([docs/modules/app-shell.md](docs/modules/app-shell.md)). +6. A dashboard endpoint called without a session must be on the ErrorInterceptor allow-list. Otherwise it is silently dropped (`EMPTY`) ([docs/modules/shared-libs.md](docs/modules/shared-libs.md)). +7. A 200 can still be an error. Check `res.hasError` (dashboard) or the per-endpoint success field (widget) as well as using `catchError` ([docs/conventions.md](docs/conventions.md#http-and-errors)). +8. A block has two ids: numeric `id` for feature CRUD, OAuth, scopes and client secrets, and string `reference_id` for the widget, billing and the Users/roles screens. Passing the wrong one fails silently ([docs/glossary.md](docs/glossary.md)). +9. In the widget, copy `OtpService.options` before adding per-call headers. It is one shared mutable object, and its headers leak into later calls. +10. The widget must not import `@proxy/services/proxy/*`, `@proxy/services/httpWrapper` or the login service. They need `AngularFireAuth` and `IToken`, which only the dashboard provides. +11. Add dashboard pages to `apps/36-blocks/src/app/panel/panel.routes.ts`. `apps/36-blocks/src/app/panel/layout/layout.routes.ts` is dead (nothing imports it). +12. Never send a client id. The current client is stored on the server against the token, and switching client is `POST switchclient` followed by a full page reload. +13. Everything `tools/set-env.js` writes ends up in a public browser bundle. Never add a real server-side secret there. When you add a key, also add it to `.env.example`. +14. Keep the `setTimeout(…, 100)` before block create/update in `create-feature.component.ts`. The payload is filled in by promises (file reads, chip lists) ([docs/modules/panel-features.md](docs/modules/panel-features.md)). +15. Branch flow is `-clean` → `stage` → `production`; the README's `development`/`main` flow is stale. PRs into `stage` get **no CI build**, so build locally first. Land any revert on `stage` too ([docs/conventions.md](docs/conventions.md#branching-and-release)). + +## Where things are + +- `apps/36-blocks/src/app/website/`: public marketing pages, login and register +- `apps/36-blocks/src/app/panel/`: the logged-in `/app` dashboard pages, each with a `.store.ts` ComponentStore +- `apps/36-blocks/src/app/core/`: the root NgRx store, the auth initializer, client registration +- `apps/36-blocks-widget/src/app/init-verification.ts`: the widget's global API +- `apps/36-blocks-widget/src/app/otp/`: widget screens, the `otp` store, `OtpService` +- `apps/36-blocks-widget/build-elements.js`: post-build step that produces the single proxy-auth.js +- `libs/`: shared code, imported only through the `@proxy/...` aliases in `tsconfig.base.json` +- `tools/set-env.js`, `tools/postbuild.js`: env generation and the version.json writer +- `apps/shared/scss/`: global SCSS and Tailwind entry shared by both apps + +## Docs map + +See [docs/README.md](docs/README.md) for every doc and when to read it. What the code can't answer is listed in [docs/open-questions.md](docs/open-questions.md); don't guess at those, ask. +When you change behaviour that a doc describes, update that doc in the same change and run `/ai-docs update`. diff --git a/docs/.ai-docs.json b/docs/.ai-docs.json index f954fef0..be4debd3 100644 --- a/docs/.ai-docs.json +++ b/docs/.ai-docs.json @@ -2,7 +2,7 @@ "skill": "ai-docs", "skill_version": "0.1.0", "created": "2026-10-14", - "last_run": { "mode": "init", "commit": "76f26ae5", "date": "2026-10-14" }, + "last_run": { "mode": "update", "commit": "395659d5", "date": "2026-10-29" }, "superseded": [ "docs/widget-window-events.md", "docs/widget-script-loading.md", diff --git a/docs/README.md b/docs/README.md index 6da603f1..fafce903 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ --- -verified_at: 76f26ae5 -verified_on: 2026-10-14 +verified_at: 395659d5 +verified_on: 2026-10-29 --- # Docs index @@ -16,6 +16,8 @@ Start with [../AGENTS.md](../AGENTS.md), then read the doc for the area you're c | [api.md](api.md) | You're touching the widget's public JS API (`initVerification`, callbacks, window events) or any backend call | | [environment.md](environment.md) | You're running or building locally, adding an env key, or touching CI or `tools/` | | [recipes.md](recipes.md) | You're making a common change: a page, a backend call, a block tab, a widget config key or screen, an env value, a lib, a release | +| [decisions.md](decisions.md) | You want to know why something is built the way it is before changing it: the single-file widget, two HTTP wrappers, build-time config, per-page stores, no Nx Cloud | +| [open-questions.md](open-questions.md) | You hit something the code can't explain. Every open question for a human, linked to the doc that holds the detail | ## Modules @@ -52,23 +54,16 @@ The older notes (docs/widget-*.md, docs/build-modernization.md, docs/angular-*.m ## Needs a human -Open questions the code can't answer. Answer them in the doc that asks, then delete the TODO. - -- **Branching:** which branch to cut `-clean` from, and whether `main` and `development` are retired ([conventions.md](conventions.md#branching-and-release)). -- **Deploy and CI:** - - the deploy target and the branch-to-environment mapping ([architecture.md](architecture.md#build), [environment.md](environment.md)) - - whether CI "Build check" passes ([environment.md](environment.md)) - - whether the `postbuild.js` hash regex matches upper-case hashes ([environment.md](environment.md)) - - whether stage `production: false` is intended ([environment.md](environment.md)) -- **SSR:** why it was removed, and whether the leftover files can be deleted ([modules/app-shell.md](modules/app-shell.md)). -- **Auth:** - - whether the backend rejects `Bearer` ([modules/shared-libs.md](modules/shared-libs.md)) - - the missing redirect after email login, and whether `/login` can return 401 ([flows/dashboard-login.md](flows/dashboard-login.md)) -- **Widget:** - - client-side AES with static keys ([modules/widget-auth.md](modules/widget-auth.md)) - - whether MSG91 and callback errors should reach the host's `failure` ([modules/widget-auth.md](modules/widget-auth.md), [flows/widget-verification.md](flows/widget-verification.md)) - - whether Tailwind preflight leaks into host pages, and whether `webpack.config.js` is dead ([modules/widget-embed.md](modules/widget-embed.md)) - - which backend permissions guard the role/permission endpoints, and the future of the `subscription` type ([modules/widget-account.md](modules/widget-account.md)) -- **Blocks:** whether `feature_id` 1/2 are stable, and the dead Lago helpers ([modules/panel-features.md](modules/panel-features.md)). -- **Panel:** whether Logs is still a supported product, and which payment provider sits behind checkout ([modules/panel-ops.md](modules/panel-ops.md)). -- **UI:** the rule for where state goes ([ui/state.md](ui/state.md)) and the `@apply` opacity limit ([ui/design-system.md](ui/design-system.md)). +Open questions the code can't answer are collected in [open-questions.md](open-questions.md), and each one is also a `[!TODO]` in the doc it concerns. Answer it in that doc, then delete the TODO and the line in open-questions.md. + +## Where the standard doc names live + +Some agent guides expect files named ARCHITECTURE, FLOWS, CONFIGURATION, DECISIONS and OPEN_QUESTIONS. In this repo they map to the existing lower-case files, so there is one source of truth per topic and no case-only name clashes on case-insensitive file systems: + +| Expected | Here | +|---|---| +| ARCHITECTURE.md (modules, data, who calls whom) | [architecture.md](architecture.md), with per-module detail in [modules/](#modules) | +| FLOWS.md (main flows step by step) | [flows/](#flows): [dashboard-login](flows/dashboard-login.md), [feature-configuration](flows/feature-configuration.md), [widget-verification](flows/widget-verification.md) | +| CONFIGURATION.md (every setting and env var) | [environment.md](environment.md) | +| DECISIONS.md | [decisions.md](decisions.md) | +| OPEN_QUESTIONS.md | [open-questions.md](open-questions.md) | diff --git a/docs/api.md b/docs/api.md index be4c2797..f764bc8b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,7 +1,7 @@ --- covers: ["apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/otp/service/otp.service.ts", "apps/36-blocks-widget/src/app/otp/service/urls/**", "apps/36-blocks-widget/src/app/otp/service/user-management-bridge.service.ts", "libs/constant/src/widget-events.ts", "libs/urls/**", "libs/services/proxy/**", "libs/services/login/**", "apps/36-blocks/src/app/panel/billing/billing.urls.ts", "apps/36-blocks/src/app/panel/billing/billing.service.ts", "apps/36-blocks/src/app/app.config.ts"] -verified_at: 76f26ae5 -verified_on: 2026-10-14 +verified_at: 395659d5 +verified_on: 2026-10-29 --- # API @@ -150,7 +150,7 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header. | PUT / DELETE | `/:referenceId/cPermission/:id` | `updatePermission` / `deletePermission` | ## Dashboard: features (blocks) configuration -`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md). +`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, `apps/36-blocks/src/app/panel/features/client-secrets/client-secrets.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md). | Method | Path | Service method | @@ -165,6 +165,8 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header. | GET / PUT / DELETE | /features/:featureId/oauthConfigs/:oauthConfigId | `getOauthConfig` / `updateOauthConfig` / `deleteOauthConfig` | | POST | /features/:featureId/oauthConfigs/:oauthConfigId/regenerateSecret | `regenerateOauthSecret` | | POST | /features/:featureId/oauthConfigs/:oauthConfigId/disable | `disableOauthConfig` | +| GET / POST | /features/:featureId/clientSecrets | `getClientSecrets` / `createClientSecret` (plaintext `client_secret` only in this response) | +| DELETE | /features/:featureId/clientSecrets/:secretId | `revokeClientSecret` (revokes; the secret stays listed with `revoked_at`) | | GET / POST | /features/:featureId/blockScopes | `getBlockScopes` / `createBlockScope` | | PUT / DELETE | /features/:featureId/blockScopes/:blockScopeId | `updateBlockScope` / `deleteBlockScope` | | GET / POST | /subscription/:refId/billableMetrics | `getAllBillableMetrics` / `createBillableMetric` | diff --git a/docs/architecture.md b/docs/architecture.md index 69435d5a..2ac0c9cf 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,7 @@ --- covers: ["apps/36-blocks/src/main.ts", "apps/36-blocks/src/app/app.config.ts", "apps/36-blocks/src/app/app.routes.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/build-elements.js", "apps/*/project.json", "tsconfig.base.json", "nx.json", "tools/*.js"] -verified_at: 76f26ae5 -verified_on: 2026-10-14 +verified_at: 395659d5 +verified_on: 2026-10-29 --- # Architecture @@ -121,6 +121,8 @@ flowchart LR ## Decisions and history +The full list, with evidence for each, is in [decisions.md](decisions.md). The ones that shape this page: + - **One file for the widget.** Customers paste one `