# StellaOps Web

Offline-first expectations mean the workspace must restore dependencies and run tests without surprise downloads. Follow the deterministic install flow below before running commands on an air-gapped runner.

## Deterministic Install (CI / Offline)

1. Pick an npm cache directory (for example `/opt/stellaops/npm-cache`) that you can copy into the Offline Kit.
2. On a connected machine, export `NPM_CONFIG_CACHE` to that directory and run `npm run ci:install`. This executes `npm ci --prefer-offline --no-audit --no-fund`, seeding the cache without audit/fund traffic.
3. Provision a headless Chromium binary by either:
   - installing `chromium`, `chromium-browser`, or `google-chrome-stable` through your distribution tooling; or
   - downloading one via `npx @puppeteer/browsers install chrome@stable --path .cache/chromium` and archiving the resulting `.cache/chromium/` directory.
4. Transfer the npm cache (and optional `.cache/chromium/`) to the offline runner, export `NPM_CONFIG_CACHE`, then execute `npm run ci:install` again.
5. Use `npm run verify:chromium` to confirm Karma can locate a browser. `npm run test:ci` enforces this check automatically.

See `docs/DeterministicInstall.md` for a detailed operator checklist covering cache priming and Chromium placement.

## Development server

Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.

## Code scaffolding

Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.

## Build

Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.

## Running unit tests

- `npm test` executes `ng test --watch=false` once after verifying a Chromium binary.
- `npm run test:ci` first calls `npm run verify:chromium` to guarantee CI/offline setups fail fast when a browser is missing.
- `npm run test:watch` keeps Karma in watch mode for local development.

`verify:chromium` prints every location inspected (environment overrides, system paths, `.cache/chromium/`). Set `CHROME_BIN` or `STELLAOPS_CHROMIUM_BIN` if you host the binary in a non-standard path.

### Headless Karma recipe (offline-friendly)

For local, deterministic Karma runs without system Chrome:

```bash
cd src/Web/StellaOps.Web
CHROME_BIN=$(pwd)/node_modules/playwright/.local-browsers/chromium-1140/chrome-linux/chrome \
LD_LIBRARY_PATH=$(pwd)/.deps/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH \
npx ng test --watch=false --browsers=ChromeHeadless --progress=false \
  --include src/app/features/policy-studio/editor/policy-editor.component.spec.ts \
  --source-map=false
```

- The `.deps` folder carries the minimal NSS/GTK libs we vendor for air-gapped nodes.
- Use one `--include` per invocation; Angular CLI rejects multiple `--include` flags.
- Monaco is file-replaced with a lightweight test stub during Karma runs; production builds are unaffected.

## Runtime configuration

The SPA loads environment details from `/config.json` at startup. During development we ship a stub configuration under `src/config/config.json`; adjust the issuer, client ID, and API base URLs to match your Authority instance. To reset, copy `src/config/config.sample.json` back to `src/config/config.json`:

```bash
cp src/config/config.sample.json src/config/config.json
```

When packaging for another environment, replace the file before building so the generated bundle contains the correct defaults. Gateways that rewrite `/config.json` at request time can override these settings without rebuilding.

## End-to-end tests

Playwright drives the high-level auth UX using the stub configuration above. Ensure the Angular dev server can bind to `127.0.0.1:4400`, then run:

```bash
npm run test:e2e
```

The Playwright config auto-starts `npm run serve:test` and intercepts Authority redirects, so no live IdP is required. For CI/offline nodes, pre-install the required browsers via `npx playwright install --with-deps` and cache the results alongside your npm cache.

## Running end-to-end tests

Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.

## Further help

To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.