# Setup

## What you need

- **Node 22 or later.** `zlib.crc32` and `Request.formData` are used. The tests were run on Node 24.12.
- **A MissionSight checkout** with `contracts/catalogue`. Only to refresh the catalogue: a copy is already in
  `vendor/missionsight`.

No database, no Docker, no cloud account and no credentials are needed for anything in this repo today.

## Install and check

```bash
npm install
npm test
npm run writing      # the house writing check over the docs
```

## Run the Collector

```bash
COLLECTOR_KEY_BHS_GATEWAY=<a key you make> COLLECTOR_KEY_RELAY=<another> npm start
```

Each source that signs names the environment variable holding its key (`data/sources/<id>.json`, `signature.key_env`).
A key is never written to a file in this repo.
- **A key that is not set.** The source's items are rejected with `not_configured`, and `GET /health` says which key
  is missing.
- **The Jira address.** `jira.base_url` in `collector.config.json` is empty, so tickets wait with that reason. The
  demo and the tests start a local stub and point the Collector at it.

## Refresh what the repo copies

```bash
npm run catalogue:sync -- ~/Forks/missionsight-catalogue   # MissionSight's catalogue, with its commit
npm run snapshots                                         # sensor snapshots from data/assets
npm run templates                                         # load templates to templates/out (xlsx, csv, instructions)
```

The sync refuses a MissionSight checkout with uncommitted changes under `contracts/`, so the copy always names a real
commit.

## Thresholds come from the Mission Studio

The Studio is the single source of thresholds. The Interchange reads a local copy of its export
(`thresholds_file` in `collector.config.json`):

```bash
node tools/fetch-thresholds.mjs --from <the folder export's thresholds.json>
node tools/fetch-thresholds.mjs --from http://127.0.0.1:4702/api/studio/projects/<id>/thresholds.json
# the Setup Studio now lives in MissionSight (packages/setup-studio, port 4702). The Causeway branch it moved from
# answers the old address, port 4692, only while that branch still runs.
curl -X POST http://127.0.0.1:4720/thresholds/reload      # if the Collector is running
```

The Studio URL needs a signed-in session: the tool reads the cookie from `STUDIO_COOKIE` in the environment. Without
it, the Studio answers "Sign in first" and the tool stops. The copy is checked against the Studio's schema
(`vendor/mission-studio`), and its project, write time and sha256 show at `GET /thresholds`.

Only a row with `usable: true` fires a rule. Anything else is a gap with its reason: no export, no row for the asset
class, not confirmed, a different unit, no value. On 7 November the Studio's exports have no usable rows, so every
interval trend shows a gap.

## The Jira hub: credentials and what it needs

The hub reads the Jira credentials of StellarView's active galaxy, the way StellarView does:
- **The galaxy.** `hub.jira.galaxy` in `collector.config.json` names one. Otherwise it is the active galaxy in
  `~/Forks/stellarview/galaxies/registry.json` (`hub.jira.galaxies_dir`).
- **The settings.** They come from that galaxy's own `.env` at `galaxies/pouches/<id>/.env`:
  - `JIRA_HOST`, `JIRA_EMAIL` and `JIRA_API_TOKEN` (required)
  - `JIRA_PROJECT_KEY` (optional)
- **Never shown.** The token is held in memory, never written to a file in this repo and never printed. A missing key
  is named; a value never is.

Other settings, each read from the environment:
- `JIRA_WEBHOOK_SECRET`: the secret a Jira admin webhook signs with (`hub.jira.webhook_secret_env`)
- `I3_WEBHOOK_KEY`: the key events from i3 are signed with (`hub.i3.webhook_key_env`)

The hub makes no call to a real Jira until all of these are in place:
   naming any other project stops with an error.
2. **The galaxy's Jira site** with the settings above.
3. **JSM Assets on that site's plan.** Check with Atlassian which plans include it. Also read the site's Assets
   custom field id into `mappings/types.json` (`jira.assets_field`).
4. **The test project's workflow and issue types,** checked against `mappings/rules.json` (Approved for work,
   Resolved, Closed) and `mappings/events.json` (Incident, Problem, Task).
5. **A webhook** from the test site to `POST /hooks/jira`, with its secret. Check the signature header there.

For i3, the vendor's interface documents are needed through the Authority (Q-35). Until then the i3 transport stays
`unknown` and every call fails visibly.

## What a live Jira test needs

The Jira adapter is built and tested against a local stub and fixtures written to Atlassian's documented response
shapes. It has never called a real Jira site. `--live` is an interface only: `node adapters/jira/cli.mjs --live`
exits with status 1 and prints the list below.

A live test needs:

2. **The active galaxy's Jira settings, read at run time:** `JIRA_HOST`, `JIRA_EMAIL`, `JIRA_API_TOKEN` and
   `JIRA_PROJECT_KEY`.
3. **That project's ids:** its service desk id and its request type ids, to replace the stub values in
   `adapters/jira/mapping.json`.
4. **Its workflow's status names,** checked against `status_back.by_status_name` in the mapping. A status the mapping
   does not name comes back as `unmapped`.
5. **Recorded responses** from the test project for the two calls, compared field by field with
   `adapters/jira/fixtures/`.

## What is a stub, and what is designed

| Part | State |
| --- | --- |
| Jira Service Management requests (the ticket listener) | Adapter built, stub-tested; live mode not built |
| Simplify i3 | The boundary only (`adapters/simplify-i3`). Its interface is not public (Q-35): transport `unknown` fails every call visibly; `simulated` is a labelled stand-in for tests and the demo. |
| Simplify i3 exports | ETL built on provisional column names; confirm with the site's i3 administrator |
| Email, SMS, Teams, Slack | Stub channels; the channel interface is in `adapters/alert-channels/interface.mjs` |
| The AI judge | Stub (`data/ai/stub-judge.json`); no model is called |
| The local relay unit | Simulated (`tools/relay.mjs`); the unit is a design |
| AWS stream, warehouse, analytics jobs | Designs (`docs/architecture.md`) |
| Rules read from policy documents | Design (`docs/document-rules.md`) |
| MQTT, BACnet, OPC UA, Modbus gateways | Not built; each will post to `POST /collect` |
