Developer Guide

Developer Guide

Everything here runs without AWS unless it says otherwise.

Get going

git clone https://github.com/rogerjeasy/wick.git && cd wick
nvm use            # Node 22, from .nvmrc
npm ci
npm run verify     # typecheck, lint, no-mocks guard and every test

npm run verify is what CI runs on every pull request. It touches no AWS.

Tool	Version	For
Node.js	22	Everything
Terraform	1.10 or newer	Deploying your own stack
AWS CLI	v2	Deploying your own stack
Docker	arm64 and amd64 builds	The agent images (arm64) and the Wick server's image (amd64)
Java 17, Android command-line tools	API 34	The Fire OS build
Vega SDK and vega CLI	SDK 0.24 was used	The Vega app

Run the whole thing on your laptop

npx vite-node -c vitest.config.ts services/mcp-server/src/__tests__/devServer.ts

The real Wick server on http://127.0.0.1:3300, over an in-memory store, with the family app on http://127.0.0.1:4173. A new account's confirmation code is always 123456. The television is stood in for, with pairing code 123456. GET /dev/allow presses Allow as the resident, and GET /dev/door rings a stand-in doorbell.

Where to work

To change...	Look in
What a card looks like, the break engine, the player	apps/tv-vega/src
The Fire OS build	apps/tv-fireos (the same source, through four adapters)
The browser television	apps/ops-console. Its engine and channels are generated from the Vega source: run npm run tv:build after changing it. A test fails unless the checked-in files match.
The family app	apps/sim-alexa
An MCP tool	services/mcp-server/src/tools
What the family may read	services/policy (the Guardian)
An agent	services/agent/src/agents, and services/agent/src/graphs
The television's channels and presses	services/edge-device/lambda
Anything shared	packages/contracts
The infrastructure	infra, one file per concern

Conventions that are enforced

• The ten invariants in AGENTS.md. Read them before changing anything on the family side, a card, or a credential. They are not style preferences.
• No mocks reach the running product. Fixtures live under __tests__. npm run check:no-mocks reads every import the way TypeScript does and fails the build otherwise.
• No red, no badges, no beeps; at least 32 pt type and 7:1 contrast. Use packages/vega-calm-ui, and write styles as a function of the theme.
• Generated files are never edited by hand: the calm points, the phrasebook, the television's engine and channels. Each has a command and a test that fails if the file drifts.
• A platform limitation goes in FRICTION.md immediately, with all six fields.
• Never commit real household data. No captures, no HAR files, no Ring snapshots.

Pull requests

1. Branch from main and keep the change to one idea.
2. Run npm run verify.
3. Open a pull request. CI runs the same checks plus a property-test job (10,000 cases for the Guardian's invariants), and main requires both.
4. A merge to main deploys the edge, the agents and the web apps over OIDC. Changes that widen what CI may do, or add an AWS service, need a laptop terraform apply first. infra/README.md says which, and in what order.

Useful commands

npm run verify	Typecheck, lint, no-mocks and every test
npm run test:property	The Guardian and the break engine on their own
npm run tv:build	Regenerate the browser television's engine, channels and catalogue
npm run calm:build	Regenerate the calm points from what was measured
npm run phrasebook:build	Regenerate the edge's copy of the phrasebook
npm run addon:check	Check the Alexa+ add-on manifest
npm run smoke:live	Live checks against a deployed stack
npm run latency:door	Time the doorbell path