@abgov/nx-adsp 12.5.0 → 12.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "12.5.0",
+  "version": "12.6.0",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",

package/src/generators/angular-app/files/AGENTS.md__tmpl__

@@ -0,0 +1,96 @@
+# AGENTS.md — <%= projectName %>
+
+Angular 19 frontend for the Alberta Digital Service Platform (ADSP).
+Generated by `nx g @abgov/nx-adsp:angular-app`.
+
+## Stack
+
+- **UI**: Angular 19 standalone + GoA design system (`@abgov/angular-components` — `Goab*` components)
+- **Auth**: `keycloak-angular` with `keycloak-js`
+- **Router**: Angular Router with `createAuthGuard` from `keycloak-angular`
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `src/main.ts` | Entry — bootstraps `AppComponent` with `appConfig`, imports `zone.js` |
+| `src/app/app.config.ts` | `provideKeycloak` (PKCE, silent SSO), `provideRouter`, `provideHttpClient` |
+| `src/app/app.component.ts` | Shell — auth state, hero banner background workaround, public API call |
+| `src/app/app.routes.ts` | Routes — `/protected` with `createAuthGuard` |
+| `src/app/protected/protected.component.ts` | Protected route — shows authenticated user info |
+| `src/environments/environment.ts` | Access URL, realm, client ID — pre-set from ADSP tenant |
+
+## Auth pattern
+
+```typescript
+import Keycloak from 'keycloak-js';
+import { inject } from '@angular/core';
+
+private keycloak = inject(Keycloak); // provided by provideKeycloak in app.config.ts
+
+this.keycloak.authenticated          // boolean
+this.keycloak.tokenParsed?.['name']  // user display name
+this.keycloak.login()
+this.keycloak.logout({ redirectUri: window.location.origin })
+```
+
+Route guard using `createAuthGuard` from `keycloak-angular`:
+
+```typescript
+const authGuard = createAuthGuard(async (_route, _state, { authenticated, keycloak }) => {
+  if (authenticated) return true;
+  await keycloak.login({ redirectUri: window.location.href });
+  return false;
+});
+```
+
+## GoA design system
+
+Components are imported from `@abgov/angular-components` with the `Goab` prefix
+and added to each standalone component's `imports` array:
+
+```typescript
+import { GoabButton, GoabAppHeader } from '@abgov/angular-components';
+
+@Component({ imports: [GoabButton, GoabAppHeader], ... })
+```
+
+**Known limitation:** `GoabHeroBanner.backgroundUrl` does not bind reliably via
+Angular's template binding due to an `@if(isReady)` timing issue inside the
+component wrapper. Use `MutationObserver` to set the property directly after
+the inner `<goa-hero-banner>` element appears — see `app.component.ts` for the
+established pattern.
+
+## Backend API calls (mean / proxy setup)
+
+If `proxy.conf.json` exists at the project root, API calls are proxied to the
+backend service in development. Use relative `/api/` paths — do not hardcode
+the service URL:
+
+```typescript
+// ✓ correct — works through proxy in dev, nginx in production
+this.http.get('/api/v1/my-resource')
+
+// ✗ wrong — bypasses proxy, won't work in production
+this.http.get('http://localhost:3333/my-service/v1/my-resource')
+```
+
+`includeBearerTokenInterceptor` (configured in `app.config.ts`) automatically
+attaches the Keycloak access token to all outgoing HTTP requests.
+In production, `nginx.conf` contains the same proxy rule routing `/api/` to
+the backend service hostname.
+
+## Adding a new route
+
+1. Create `src/app/my-feature/my-feature.component.ts` as a standalone component
+2. Add the route to `src/app/app.routes.ts`
+3. Add required `Goab*` components to the new component's `imports` array
+
+## What NOT to change
+
+- `app.config.ts` — `provideKeycloak` initialises keycloak-js once; do not
+  create a second Keycloak instance elsewhere
+- `silent-check-sso.html` — served from `public/`; required for keycloak-js
+  silent SSO check on page load
+- `environments/environment.ts` — access URL and realm are pre-configured for
+  the ADSP tenant; override at runtime via environment variables

package/src/generators/express-service/files/AGENTS.md__tmpl__

@@ -0,0 +1,76 @@
+# AGENTS.md — <%= projectName %>
+
+Node/Express backend service for the Alberta Digital Service Platform (ADSP).
+Generated by `nx g @abgov/nx-adsp:express-service`.
+
+## Stack
+
+- **Runtime**: Node.js + Express
+- **Auth**: passport.js with tenant strategy from `@abgov/adsp-service-sdk`
+- **Config**: `envalid` with `.env` file (see `src/environment.ts`)
+- **SDK**: `@abgov/adsp-service-sdk` — provides service registration, auth,
+  event publishing, configuration management, and service discovery
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `src/main.ts` | App entry — SDK init, middleware, routes, server start |
+| `src/environment.ts` | Validated env config with defaults pre-set from ADSP tenant |
+
+## SDK capabilities
+
+`initializeService()` returns `capabilities`:
+
+```typescript
+const { logger, tenantStrategy, traceHandler, configurationHandler,
+        healthCheck, directory, tokenProvider, eventService } = capabilities;
+```
+
+To resolve another ADSP service URL:
+
+```typescript
+const url = await directory.getServiceUrl(AdspId.parse('urn:ads:platform:file-service'));
+```
+
+To call another service with an access token:
+
+```typescript
+const token = await tokenProvider.getAccessToken();
+```
+
+## Adding routes
+
+Add route handlers in `main.ts` under the `/<%= projectName %>/v1` path prefix:
+
+```typescript
+app.get('/<%= projectName %>/v1/my-resource', (req, res) => {
+  const user = req.user; // null for anonymous, populated for authenticated
+  res.json({ ... });
+});
+```
+
+`passport.authenticate(['tenant', 'anonymous'])` is applied to the entire
+`/<%= projectName %>/v1` prefix — check `req.user` inside handlers to
+distinguish authenticated from anonymous access.
+
+## Frontend proxy integration (mern / mean stacks)
+
+When this service is paired with a React or Angular frontend via the `mern` or
+`mean` generators, the frontend proxies `/api/` to this service:
+
+- **Dev** (webpack / Vite): `/api/v1/my-resource` → `/<%= projectName %>/v1/my-resource` on `localhost:3333`
+- **Production** (nginx): same rewrite via the nginx proxy block in the frontend app
+
+All API routes in this service live under `/<%= projectName %>/v1/`. The proxy
+rewrites the frontend's `/api/` prefix to `/<%= projectName %>/` before the
+request reaches Express, so `/<%= projectName %>/v1/public` maps to the
+frontend's `/api/v1/public`.
+
+## What NOT to change
+
+- `initializeService(...)` config — `CLIENT_ID` and `CLIENT_SECRET` are read
+  from environment; do not hardcode credentials
+- The passport strategy setup — the tenant strategy handles JWT validation
+- `configurationHandler` on the API path — provides configuration service
+  integration; keep it applied before route handlers

package/src/generators/react-app/files/AGENTS.md__tmpl__

@@ -0,0 +1,76 @@
+# AGENTS.md — <%= projectName %>
+
+React frontend for the Alberta Digital Service Platform (ADSP).
+Generated by `nx g @abgov/nx-adsp:react-app`.
+
+## Stack
+
+- **UI**: React 18 + GoA design system (`@abgov/react-components` — `Goab*` components)
+- **Auth**: `keycloak-js` via Redux Toolkit slice (`src/app/user.slice.ts`)
+- **State**: Redux Toolkit — store in `src/store.ts`
+- **Router**: React Router v6
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `src/main.tsx` | Entry — Redux Provider, BrowserRouter, dispatches `initializeUser()` after render |
+| `src/app/user.slice.ts` | Keycloak auth — login, logout, token refresh, `getAccessToken()` |
+| `src/app/start.slice.ts` | Example public/private API calls |
+| `src/app/config.slice.ts` | Loads ADSP directory service endpoints on startup |
+| `src/app/intake.slice.ts` | Application domain state — extend this for your feature |
+| `src/store.ts` | Redux store — add new slices here |
+| `src/environments/environment.ts` | Access URL, realm, client ID — pre-set from ADSP tenant |
+
+## Auth pattern
+
+```typescript
+import { getAccessToken, loginUser, logoutUser, userSelector } from './user.slice';
+
+// In a component:
+const { authenticated, name } = useSelector(userSelector);
+dispatch(loginUser());   // redirects to Keycloak
+dispatch(logoutUser());  // redirects to Keycloak logout
+
+// In a thunk (for authenticated API calls):
+const token = await getAccessToken(); // refreshes token if needed
+```
+
+## GoA design system
+
+Components are imported from `@abgov/react-components` with the `Goab` prefix:
+
+```typescript
+import { GoabButton, GoabAppHeader, GoabButtonGroup } from '@abgov/react-components';
+```
+
+## Adding a new Redux slice
+
+1. Create `src/app/my-feature.slice.ts` using `createSlice` / `createAsyncThunk`
+2. Export the reducer and add it to `src/store.ts`
+
+## Backend API calls (mern / proxy setup)
+
+If `proxy.conf.json` exists at the project root, API calls are proxied to the
+backend service in development. Use relative `/api/` paths — do not hardcode
+the service URL:
+
+```typescript
+// ✓ correct — works through proxy in dev, nginx in production
+const response = await fetch('/api/v1/my-resource');
+
+// ✗ wrong — bypasses proxy, won't work in production
+const response = await fetch('http://localhost:3333/my-service/v1/my-resource');
+```
+
+In production, `nginx.conf` contains the same proxy rule routing `/api/` to
+the backend service hostname.
+
+## What NOT to change
+
+- `user.slice.ts` — keycloak-js is initialised once per app lifecycle; do not
+  create a second Keycloak instance
+- `environments/environment.ts` — access URL and realm are pre-configured for
+  the ADSP tenant; override at runtime via deployment config
+- `silent-check-sso.html` — required for keycloak-js silent SSO; must be served
+  from the app root