Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

43.4 KB
Raw Blame
#!/usr/bin/env node
/**
 * A real Home Assistant, on demand, for the home lane's live tests.
 *
 * Every live test in this lane needs the same thing: an instance that is
 * onboarded, holds a long-lived token, and contains a house worth asserting on
 * (floors, areas, a lock, scenes, the MCP server). Before this script each test
 * and each developer built that by hand from the README, which is how six
 * slightly different instances came to exist and how a version difference could
 * hide as "works on my machine".
 *
 *   node scripts/home-test-instance.mjs --up --onboard --seed --json
 *   eval "$(node scripts/home-test-instance.mjs --up --onboard --seed --env)"
 *   node scripts/home-test-instance.mjs --down
 *
 * Flags combine in that order, so one command takes you from nothing to a
 * seeded house and prints the URL and token. Every step is idempotent: running
 * it twice is a no-op that reprints the same connection details.
 *
 * Safety, and read the second half of this before you type `--down`:
 *
 * The harness stamps every container it creates with a label and REFUSES to
 * stop, restart or remove a container that does not carry it, so nothing else
 * running on this machine (the voice lane's own Home Assistant, say) can be
 * taken by a stray name. It also never touches a config directory outside the
 * gitignored `.ha-config-*` prefix, because those directories hold real access
 * tokens.
 *
 * That label says "this harness made it", NOT "you made it". Concurrent agents
 * share this machine and all of them use this script, so a peer's house carries
 * the same label yours does and the check above cannot tell them apart. The
 * lane name is the only thing that separates two houses. Passing somebody
 * else's `--name` to `--down` therefore destroys a house a live run may be
 * inside, which is exactly what happened on 2026-09-09. `assertNotInUse` is the
 * guard that now stands in front of that: a house handed out in the last half
 * hour needs `--force`.
 */

import { spawn } from 'node:child_process';
import fs from 'node:fs';
import net from 'node:net';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');

/** The label that marks a container as ours. Nothing without it is ever touched. */
const LABEL = 'ws.three.home-test';
/** How long after a run took a house it still counts as in use. See assertNotInUse. */
const IN_USE_MS = 30 * 60 * 1000;
const IMAGE = 'ghcr.io/home-assistant/home-assistant';
const CLIENT_NAME = 'three.ws home lane';

const USER = { name: 'Home Lane', username: 'threews', password: 'threews-home-lane' };

/**
 * The entry point lives at the bottom of this file, below every declaration it
 * uses. A top-level call above a `class` declaration reads its binding in the
 * temporal dead zone, which throws on every engine that checks it.
 */
async function main() {
	const argv = process.argv.slice(2);
	const opts = parseArgs(argv);

	if (opts.help || !argv.length) {
		usage();
		process.exit(argv.length ? 0 : 1);
	}

	const instance = describeInstance(opts.name, opts.version);
	log = opts.json || opts.env ? () => {} : (...args) => console.error(...args);
	emit = (payload) => {
		if (opts.json) console.log(JSON.stringify({ ok: true, ...payload }, null, '\t'));
		// --env exists so the documented one-liner is literally true:
		//   eval "$(node scripts/home-test-instance.mjs --up --onboard --seed --env)"
		// The bare form already printed the two variables, but without `export`
		// they land in the eval's own shell and vanish, which is the kind of
		// almost-working instruction that sends someone back to building a house
		// by hand. Progress goes to stderr either way, so stdout stays evaluable.
		else if (opts.env) {
			if (payload.baseUrl) console.log(`export HOME_ASSISTANT_URL=${shellQuote(payload.baseUrl)}`);
			if (payload.token) console.log(`export HOME_ASSISTANT_TOKEN=${shellQuote(payload.token)}`);
		} else if (payload.baseUrl) {
			console.log(`HOME_ASSISTANT_URL=${payload.baseUrl}`);
			if (payload.token) console.log(`HOME_ASSISTANT_TOKEN=${payload.token}`);
		}
	};

	try {
		// Several vitest forks reach for the same named instance at once, and two
		// simultaneous `docker run --name` calls means one of them fails. The lock
		// makes the second caller wait for the first to finish building the house
		// and then reuse it, which is what "idempotent" has to mean under
		// concurrency.
		const state = await withLock(instance, async () => {
			let current = readState(instance);

			if (opts.down) {
				const removed = await down(instance, current, { force: opts.force });
				emit({ action: 'down', name: instance.name, ...removed });
				return null;
			}

			// Stop and start keep the house: the config directory, the token and
			// the seeded entities all survive, so a test can take the instance off
			// the network and put it back without paying for another onboarding.
			// That is the only honest way to exercise a home that stops answering.
			if (opts.stop) current = await stop(instance, current);
			if (opts.start) current = await start(instance, current);

			if (opts.up) current = await up(instance, current, { seedNow: opts.seed });
			if (!current) current = requireState(instance);

			if (opts.onboard) current = await onboard(instance, current);
			if (opts.seed) current = await seed(instance, current, { alreadyInConfig: Boolean(opts.up) });
			return current;
		});
		if (!state) return;

		// Stamp WHEN this house was last handed to somebody, so `--down` can tell
		// a lane that finished hours ago from one a run is living inside right
		// now. See `assertNotInUse`.
		writeState(instance, { ...state, lastAcquiredAt: new Date().toISOString() });

		emit({
			action: 'ready',
			name: instance.name,
			version: state.version,
			haVersion: state.haVersion || null,
			container: instance.container,
			port: state.port,
			baseUrl: state.baseUrl,
			token: state.token || null,
			seeded: Boolean(state.seeded),
			seed: state.seedResult || null,
			configDir: path.relative(ROOT, instance.configDir),
		});
	} catch (err) {
		if (opts.json) console.log(JSON.stringify({ ok: false, error: err.message }, null, '\t'));
		// Under --env, stdout is being eval'd. A failure must leave it empty
		// rather than feeding a shell half a sentence.

		console.error(`home-test-instance: ${err.message}`);
		process.exitCode = 1;
	}
}

/** Progress goes to stderr so --json owns stdout. Bound by main(). */
let log = () => {};
let emit = () => {};

// ---------------------------------------------------------------- lifecycle

/**
 * Start a container on a free port and wait until Home Assistant answers.
 * Reuses a running instance rather than replacing it, so two tests that both
 * ask for the same named instance share one house instead of racing.
 */
async function up(inst, state, { seedNow }) {
	const existing = await inspect(inst.container);
	if (existing?.running && state?.port) {
		log(`[up] reusing ${inst.container} on :${state.port}`);
		await waitForHomeAssistant(state.baseUrl);
		return writeState(inst, { ...state, running: true });
	}
	if (existing && !existing.running) {
		assertOurs(existing, inst.container);
		await docker(['rm', '-f', inst.container]);
	}

	fs.mkdirSync(inst.configDir, { recursive: true });
	// Writing configuration.yaml before the first boot is the difference between
	// a 40s start and a 40s start plus a 40s restart. When --up and --seed are
	// asked for together the demo house is therefore configured up front; a
	// later standalone --seed appends and restarts instead.
	writeConfiguration(inst, { demo: seedNow });

	const port = await freePort();
	log(`[up] starting ${inst.image} on :${port}`);
	await docker([
		'run', '-d',
		'--name', inst.container,
		'--label', `${LABEL}=1`,
		'--label', `${LABEL}.name=${inst.name}`,
		'-p', `127.0.0.1:${port}:8123`,
		'-v', `${inst.configDir}:/config`,
		'-e', 'TZ=UTC',
		inst.image,
	]);

	const baseUrl = `http://127.0.0.1:${port}`;
	const next = writeState(inst, { name: inst.name, version: inst.version, port, baseUrl, running: true, demoInConfig: Boolean(seedNow) });
	const haVersion = await waitForHomeAssistant(baseUrl);
	log(`[up] ${inst.container} is up, Home Assistant ${haVersion || 'unknown'}`);
	return writeState(inst, { ...next, haVersion });
}

/**
 * Remove the container and its config directory. Refuses anything it did not
 * create, and reports honestly when there was nothing to remove.
 */
/**
 * Take the house off the network without destroying it.
 *
 * `--down` removes the container AND the config directory, which throws away
 * the access token and every seeded entity: recovering from it costs a full
 * onboarding. A house that has stopped answering is a state the product has to
 * render, so exercising it must not cost two minutes and a new token. Stopping
 * the container is what actually happens to a real house whose power went out,
 * and `--start` puts it back exactly as it was.
 */
async function stop(inst, state) {
	const current = state || requireState(inst);
	const existing = await inspect(inst.container);
	if (!existing) throw new Error(`no container named "${inst.container}" to stop. Run --up first.`);
	assertOurs(existing, inst.container);
	if (existing.running) {
		// Thirty seconds, not ten: Home Assistant flushes its recorder database on
		// SIGTERM and a ten-second grace killed it (exit 137) every time, which
		// risks the sqlite store the seeded house lives in.
		await docker(['stop', '--time', '30', inst.container]);
		log(`[stop] stopped ${inst.container}`);
	} else {
		log(`[stop] ${inst.container} was already stopped`);
	}
	return writeState(inst, { ...current, running: false });
}

/** Put a stopped house back on the same port, and wait until it answers. */
async function start(inst, state) {
	const current = state || requireState(inst);
	const existing = await inspect(inst.container);
	if (!existing) throw new Error(`no container named "${inst.container}" to start. Run --up first.`);
	assertOurs(existing, inst.container);
	if (!existing.running) {
		await docker(['start', inst.container]);
		log(`[start] started ${inst.container}`);
	}
	// Docker publishes the same port mapping it was created with, so the base
	// URL in the state file is still the right one; what is not guaranteed is
	// that Home Assistant is ready behind it yet.
	await waitForHomeAssistant(current.baseUrl);
	// Answering is not the same as running. Straight after a restart /api/config
	// reports `state: NOT_RUNNING` for several seconds while components come
	// back, and a caller that connected in that window would read a house with
	// no entities in it and blame the product. Once there is a token to ask
	// with, wait for the house to say it is running.
	if (current.token) await waitForRunning(current.baseUrl, current.token);
	return writeState(inst, { ...current, running: true });
}

async function down(inst, state, { force = false } = {}) {
	const existing = await inspect(inst.container);
	let removedContainer = false;
	if (existing) {
		assertOurs(existing, inst.container);
		assertNotInUse(inst, state, { force });
		await docker(['rm', '-f', inst.container]);
		removedContainer = true;
		log(`[down] removed ${inst.container}`);
	}

	let removedConfig = false;
	const dir = inst.configDir;
	if (fs.existsSync(dir)) {
		if (!path.basename(dir).startsWith('.ha-config-') || path.dirname(dir) !== ROOT) {
			throw new Error(`refusing to delete ${dir}: not a harness config directory`);
		}
		// Home Assistant runs as root in the container, so /config comes back
		// owned by root and an ordinary rm cannot clear it. Hand ownership back
		// through a throwaway container on the image we already have locally,
		// then delete from here. A config directory left behind is not litter:
		// it holds a working access token.
		await docker([
			'run', '--rm',
			'-v', `${dir}:/target`,
			'--entrypoint', 'chown',
			inst.image,
			'-R', `${process.getuid()}:${process.getgid()}`, '/target',
		]).catch((err) => log(`[down] could not reclaim ownership of ${path.relative(ROOT, dir)}: ${err.message}`));
		fs.rmSync(dir, { recursive: true, force: true });
		removedConfig = true;
		log(`[down] removed ${path.relative(ROOT, dir)}`);
	}
	if (!removedContainer && !removedConfig) log(`[down] nothing to remove for "${inst.name}"`);
	return { removedContainer, removedConfig };
}

// ---------------------------------------------------------------- onboarding

/**
 * Walk Home Assistant's real onboarding API and mint a long-lived token.
 *
 * This is the flow the browser performs on a fresh install: create the owner,
 * exchange the returned auth code for a session, finish the remaining steps,
 * then ask the WebSocket API for a long-lived token. No file is edited to fake
 * a user into existence.
 */
async function onboard(inst, state) {
	if (state.token && (await tokenWorks(state.baseUrl, state.token))) {
		log('[onboard] already onboarded, token still valid');
		return state;
	}

	const clientId = `${state.baseUrl}/`;
	// A finished instance unregisters its onboarding views, so on 2026.9 this
	// answers 404 rather than listing four completed steps. That is the state a
	// harness meets whenever a run was interrupted after the container came up
	// but before the token was minted, or whenever a config directory outlived
	// its state file, and it used to end the run with a raw
	// "GET /api/onboarding returned 404" that reads like the instance is broken.
	// No list means onboarding is over, which is exactly the case the owner-login
	// path below already handles.
	const steps = await json(`${state.baseUrl}/api/onboarding`, { optional: true });
	const done = steps ? new Set(steps.filter((s) => s.done).map((s) => s.step)) : new Set(['user', 'core_config', 'analytics', 'integration']);

	// An instance can be onboarded while the harness holds no token: an
	// interrupted run, or a config directory that outlived its state file. The
	// owner account is one this harness created and whose password it knows, so
	// the recovery is a real login rather than a dead end.
	let session;
	if (done.has('user')) {
		log('[onboard] already onboarded, signing in as the owner');
		session = await exchangeCode(state.baseUrl, clientId, await login(state.baseUrl, clientId));
	} else {
		log('[onboard] creating the owner account');
		const { auth_code: userCode } = await json(`${state.baseUrl}/api/onboarding/users`, {
			method: 'POST',
			body: { client_id: clientId, ...USER, language: 'en' },
		});
		session = await exchangeCode(state.baseUrl, clientId, userCode);
	}

	// core_config and analytics are separate steps and each has appeared and
	// moved between releases, so a missing one is skipped rather than fatal.
	for (const step of done.has('user') ? [] : ['core_config', 'analytics']) {
		if (done.has(step)) continue;
		await json(`${state.baseUrl}/api/onboarding/${step}`, {
			method: 'POST',
			token: session.access_token,
			body: step === 'analytics' ? { preferences: { base: false } } : {},
			optional: true,
		});
	}
	if (!done.has('integration')) {
		await json(`${state.baseUrl}/api/onboarding/integration`, {
			method: 'POST',
			token: session.access_token,
			body: { client_id: clientId, redirect_uri: clientId },
			optional: true,
		});
	}

	log('[onboard] minting a long-lived access token');
	const ws = await WsSession.open(state.baseUrl, session.access_token);
	let token;
	try {
		token = await ws.send({
			type: 'auth/long_lived_access_token',
			client_name: `${CLIENT_NAME} ${Date.now()}`,
			lifespan: 30,
		});
	} finally {
		ws.close();
	}

	return writeState(inst, { ...state, token, haVersion: ws.haVersion || state.haVersion });
}

/**
 * Home Assistant's real username/password login flow, which is what the login
 * page performs. Returns the authorization code to exchange for a session.
 */
async function login(baseUrl, clientId) {
	const flow = await json(`${baseUrl}/auth/login_flow`, {
		method: 'POST',
		body: { client_id: clientId, handler: ['homeassistant', null], redirect_uri: clientId, type: 'authorize' },
	});
	const result = await json(`${baseUrl}/auth/login_flow/${flow.flow_id}`, {
		method: 'POST',
		body: { client_id: clientId, username: USER.username, password: USER.password },
	});
	if (result?.type !== 'create_entry' || !result.result) {
		throw new Error(`login as ${USER.username} did not produce an auth code: ${JSON.stringify(result).slice(0, 200)}`);
	}
	return result.result;
}

async function exchangeCode(baseUrl, clientId, code) {
	const res = await fetch(`${baseUrl}/auth/token`, {
		method: 'POST',
		headers: { 'content-type': 'application/x-www-form-urlencoded' },
		body: new URLSearchParams({ grant_type: 'authorization_code', code, client_id: clientId }),
	});
	if (!res.ok) throw new Error(`token exchange returned ${res.status}: ${await res.text()}`);
	return res.json();
}

// ---------------------------------------------------------------- seeding

/**
 * Turn a bare instance into a house: demo entities, a floor, three areas with
 * entities assigned, two scenes, the MCP server, and a lock exposed to Assist.
 *
 * Everything is created through the real APIs and everything is idempotent, so
 * a second --seed finds what the first one made and changes nothing.
 */
async function seed(inst, state, { alreadyInConfig }) {
	if (!state.token) throw new Error('seed needs a token: run --onboard first.');

	if (!state.demoInConfig && !alreadyInConfig) {
		log('[seed] enabling the demo integration and restarting');
		writeConfiguration(inst, { demo: true });
		const existing = await inspect(inst.container);
		assertOurs(existing, inst.container);
		await docker(['restart', inst.container]);
		await waitForHomeAssistant(state.baseUrl);
		state = writeState(inst, { ...state, demoInConfig: true });
	}

	const ws = await WsSession.open(state.baseUrl, state.token);
	const created = { floors: 0, areas: 0, assigned: 0, scenes: 0, exposed: 0, mcp: false };
	try {
		await waitFor(
			async () => {
				const states = await ws.send({ type: 'get_states' });
				return states.some((s) => s.entity_id.startsWith('light.')) && states.some((s) => s.entity_id.startsWith('lock.'));
			},
			{ timeout: 120_000, label: 'demo entities to appear' },
		);

		const floor = await ensureFloor(ws, 'Ground Floor');
		created.floors = floor.created ? 1 : 0;

		// Only entities that reached the ENTITY REGISTRY can hold an area, and the
		// demo's locks never do: they carry no unique_id, so they exist as states
		// and nothing more. Plan the rooms from the registry and let the states
		// answer for everything else, rather than assigning an area to an entity
		// that cannot have one and counting it as furnished.
		const registry = await ws.send({ type: 'config/entity_registry/list' }).catch(() => []);
		const states = await ws.send({ type: 'get_states' });
		const registered = (domain) => registry.filter((e) => e.entity_id.startsWith(`${domain}.`)).map((e) => e.entity_id);
		const byDomain = (domain) => states.filter((s) => s.entity_id.startsWith(`${domain}.`)).map((s) => s.entity_id);

		const lights = registered('light');
		const climate = registered('climate');
		const covers = registered('cover');
		const fans = registered('fan');
		const switches = registered('switch');
		const doorSensors = registered('binary_sensor');
		const locks = byDomain('lock');

		// A furnished house, not a demo of one. Every room gets light, and the
		// rooms that should have something to secure get a cover or a door
		// sensor, because a room graph whose security rollup is null everywhere
		// proves nothing about the rollup. Entities come from whatever this
		// release's demo actually registers, so a demo change shows up as fewer
		// assignments rather than as a broken seed.
		const plan = [
			{ name: 'Living Room', entities: [lights[0], climate[0], covers[0], switches[0]] },
			{ name: 'Kitchen', entities: [lights[1], covers[1], fans[0], doorSensors[0]] },
			// The bedroom is deliberately left with nothing securable in it. A house
			// where every room has a door is a house that cannot tell a real
			// "nothing to secure here" apart from a false "all secure", and the
			// room graph draws that distinction on purpose.
			{ name: 'Bedroom', entities: [lights[2], climate[1], fans[1]] },
			{ name: 'Front Door', entities: [lights[3], covers[2], doorSensors[1]] },
		].map((room) => ({ ...room, entities: room.entities.filter(Boolean) }));

		for (const room of plan) {
			const area = await ensureArea(ws, room.name, floor.floor_id);
			if (area.created) created.areas += 1;
			for (const entityId of room.entities) {
				// A demo entity with no unique_id never reaches the entity registry
				// and cannot hold an area. Count what actually landed, so the seed
				// report is a measurement rather than a count of attempts.
				const assigned = await ws
					.send({ type: 'config/entity_registry/update', entity_id: entityId, area_id: area.area_id })
					.then(() => true)
					.catch(() => false);
				if (assigned) created.assigned += 1;
				else created.unregistered = [...(created.unregistered || []), entityId];
			}
		}

		// The two scenes every intent test in the lane resolves against. Bedtime
		// deliberately touches the lock, because "good night locks the door" is
		// the case where the confirmation gate has to fire on a macro.
		const scenes = [
			{ id: 'threews_bedtime', name: 'Bedtime', entities: sceneEntities({ lights: lights.slice(0, 2), off: true, lock: locks[0], lockState: 'locked' }) },
			{ id: 'threews_away_mode', name: 'Away Mode', entities: sceneEntities({ lights, off: true, lock: locks[0], lockState: 'locked' }) },
		];
		for (const scene of scenes) {
			const res = await fetch(`${state.baseUrl}/api/config/scene/config/${scene.id}`, {
				method: 'POST',
				headers: { authorization: `Bearer ${state.token}`, 'content-type': 'application/json' },
				body: JSON.stringify({ id: scene.id, name: scene.name, entities: scene.entities }),
			});
			if (res.ok) created.scenes += 1;
			else log(`[seed] scene ${scene.name} returned ${res.status}`);
		}
		await ws.send({ type: 'call_service', domain: 'scene', service: 'reload', service_data: {} }).catch(() => {});

		// Expose the lock to Assist. This is the configuration that makes Home
		// Assistant's own intent__HassTurnOff unlock a door, which is the finding
		// the whole safety gate exists for: the lane must test against a house
		// where that is actually reachable.
		if (locks[0]) {
			created.exposed = (await exposeToAssist(ws, [locks[0], ...lights.slice(0, 1)])) ? 1 : 0;
			created.exposeCommand = ws.exposeCommand || null;
		}

		created.mcp = await ensureMcpServer(state);
		created.entities = { lights: lights.length, locks: locks.length, climate: climate.length };
		created.lock = locks[0] || null;
		created.light = lights[0] || null;
	} finally {
		ws.close();
	}

	log(
		`[seed] ${created.areas} areas created, ${created.assigned} entities assigned, ${created.scenes} scenes, mcp_server ${created.mcp ? 'enabled' : 'unavailable'}`,
	);
	return writeState(inst, { ...state, seeded: true, seedResult: created });
}

function sceneEntities({ lights = [], off = true, lock, lockState = 'locked' }) {
	const entities = {};
	for (const id of lights) entities[id] = off ? 'off' : 'on';
	if (lock) entities[lock] = lockState;
	return entities;
}

async function ensureFloor(ws, name) {
	const floors = await ws.send({ type: 'config/floor_registry/list' }).catch(() => []);
	const found = floors.find((f) => f.name === name);
	if (found) return { ...found, created: false };
	const made = await ws.send({ type: 'config/floor_registry/create', name, level: 0 });
	return { ...made, created: true };
}

async function ensureArea(ws, name, floorId) {
	const areas = await ws.send({ type: 'config/area_registry/list' });
	const found = areas.find((a) => a.name === name);
	if (found) {
		if (floorId && found.floor_id !== floorId) {
			await ws.send({ type: 'config/area_registry/update', area_id: found.area_id, floor_id: floorId }).catch(() => {});
		}
		return { ...found, created: false };
	}
	const made = await ws.send({ type: 'config/area_registry/create', name, ...(floorId ? { floor_id: floorId } : {}) });
	if (floorId && !made.floor_id) {
		await ws.send({ type: 'config/area_registry/update', area_id: made.area_id, floor_id: floorId }).catch(() => {});
	}
	return { ...made, created: true };
}

/**
 * Set up the `mcp_server` integration through its real config flow. It is a
 * config-entry integration with no YAML form, so this drives the same HTTP flow
 * the Settings UI drives. Returns false when the release does not ship it,
 * which is a supported outcome: the MCP channel is an upgrade, not a
 * requirement.
 */
async function ensureMcpServer(state) {
	const headers = { authorization: `Bearer ${state.token}`, 'content-type': 'application/json' };
	const entries = await fetch(`${state.baseUrl}/api/config/config_entries/entry`, { headers })
		.then((r) => (r.ok ? r.json() : []))
		.catch(() => []);
	if (entries.some((e) => e.domain === 'mcp_server')) return true;

	const start = await fetch(`${state.baseUrl}/api/config/config_entries/flow`, {
		method: 'POST',
		headers,
		body: JSON.stringify({ handler: 'mcp_server', show_advanced_options: false }),
	});
	if (!start.ok) return false;
	const flow = await start.json();
	if (flow.type === 'create_entry') return true;
	if (!flow.flow_id) return false;

	// The single step asks which LLM API to expose. Releases disagree on the
	// shape: a single-value select in the release the integration landed in, a
	// multi-select since. Read the flow's own schema rather than sniffing a
	// version string, and send whichever shape this instance asked for.
	const finish = await fetch(`${state.baseUrl}/api/config/config_entries/flow/${flow.flow_id}`, {
		method: 'POST',
		headers,
		body: JSON.stringify({ llm_hass_api: llmApiValue(flow.data_schema) }),
	});
	if (!finish.ok) return false;
	const result = await finish.json();
	return result.type === 'create_entry';
}

/**
 * "assist" in the shape this instance's config flow asks for.
 *
 * @param {Array} schema the flow's own data_schema
 */
function llmApiValue(schema) {
	const field = (Array.isArray(schema) ? schema : []).find((f) => f.name === 'llm_hass_api');
	const options = field?.selector?.select?.options || [];
	const assist = options.find((o) => (o?.value ?? o) === 'assist');
	const value = assist ? (assist.value ?? assist) : 'assist';
	return field?.selector?.select?.multiple ? [value] : value;
}

/**
 * Expose entities to Assist, which is what makes Home Assistant's own
 * `intent__HassTurnOff` able to unlock a real door. The command was
 * `homeassistant/expose_entity/set` when exposure settings landed and is
 * `homeassistant/expose_entity` now, so ask the instance which one it answers
 * to instead of branching on a version number.
 */
async function exposeToAssist(ws, entityIds) {
	const ids = entityIds.filter(Boolean);
	if (!ids.length) return false;
	const candidates = ['homeassistant/expose_entity', 'homeassistant/expose_entity/set'];
	for (const type of candidates) {
		try {
			await ws.send({ type, assistants: ['conversation'], entity_ids: ids, should_expose: true });
			ws.exposeCommand = type;
			return true;
		} catch (err) {
			if (!/unknown_command/.test(err.message)) throw err;
		}
	}
	return false;
}

// ---------------------------------------------------------------- websocket

/** A minimal authenticated Home Assistant WebSocket session. */
class WsSession {
	static async open(baseUrl, token) {
		const url = `${baseUrl.replace(/^http/, 'ws')}/api/websocket`;
		const socket = new WebSocket(url);
		const session = new WsSession(socket);
		await new Promise((resolve, reject) => {
			const timer = setTimeout(() => reject(new Error(`websocket handshake to ${url} timed out`)), 30_000);
			socket.onerror = () => {
				clearTimeout(timer);
				reject(new Error(`could not open ${url}`));
			};
			socket.onclose = () => {
				clearTimeout(timer);
				reject(new Error(`${url} closed during the handshake`));
			};
			socket.onmessage = (event) => {
				const msg = JSON.parse(event.data);
				if (msg.type === 'auth_required') {
					session.haVersion = msg.ha_version || null;
					socket.send(JSON.stringify({ type: 'auth', access_token: token }));
					return;
				}
				if (msg.type === 'auth_ok') {
					session.haVersion = msg.ha_version || session.haVersion;
					clearTimeout(timer);
					socket.onclose = null;
					session.listen();
					resolve();
					return;
				}
				if (msg.type === 'auth_invalid') {
					clearTimeout(timer);
					reject(new Error('Home Assistant rejected the token.'));
				}
			};
		});
		return session;
	}

	constructor(socket) {
		this.socket = socket;
		this.nextId = 1;
		this.pending = new Map();
		this.haVersion = null;
	}

	listen() {
		this.socket.onmessage = (event) => {
			const msg = JSON.parse(event.data);
			if (msg.type !== 'result') return;
			const entry = this.pending.get(msg.id);
			if (!entry) return;
			this.pending.delete(msg.id);
			if (msg.success) entry.resolve(msg.result);
			else entry.reject(new Error(`${msg.error?.code || 'error'}: ${msg.error?.message || 'unknown'}`));
		};
		this.socket.onclose = () => {
			for (const entry of this.pending.values()) entry.reject(new Error('websocket closed'));
			this.pending.clear();
		};
	}

	send(message) {
		const id = this.nextId++;
		return new Promise((resolve, reject) => {
			const timer = setTimeout(() => {
				this.pending.delete(id);
				reject(new Error(`${message.type} timed out`));
			}, 30_000);
			this.pending.set(id, {
				resolve: (value) => {
					clearTimeout(timer);
					resolve(value);
				},
				reject: (err) => {
					clearTimeout(timer);
					reject(err);
				},
			});
			this.socket.send(JSON.stringify({ ...message, id }));
		});
	}

	close() {
		try {
			this.socket.close();
		} catch {
			// A socket that is already gone needs no closing.
		}
	}
}

// ---------------------------------------------------------------- helpers

/**
 * Wait until Home Assistant is serving, whatever point in its life it is at.
 *
 * Readiness is asked in a way that does not depend on onboarding state, and
 * that is the whole subtlety here. `/api/onboarding` answers 200 while the
 * instance is fresh, and on 2026.9 it answers **404** once onboarding is
 * finished, because the onboarding views are unregistered when they are done.
 * A probe that only accepted 200 or 401 therefore worked exactly once per
 * container: the first `--up` on a fresh instance passed, and every later call
 * that reused or restarted that same instance sat for the full 180 seconds and
 * reported a healthy house as a timeout. Measured on 2026.9.0: an onboarded
 * instance answers `/` 200, `/api/` 401, `/manifest.json` 200,
 * `/api/onboarding` 404.
 *
 * So: any answer from `/api/onboarding` other than a 5xx means the HTTP stack
 * is up, and a 401 from `/api/` means the API layer is up. Either is proof the
 * house is answering.
 */
async function waitForHomeAssistant(baseUrl) {
	let version = null;
	await waitFor(
		async () => {
			const onboarding = await fetch(`${baseUrl}/api/onboarding`, { signal: AbortSignal.timeout(4000) }).catch(() => null);
			if (onboarding && onboarding.status < 500) return true;
			const api = await fetch(`${baseUrl}/api/`, { signal: AbortSignal.timeout(4000) }).catch(() => null);
			return Boolean(api && api.status === 401);
		},
		{ timeout: 180_000, label: `${baseUrl} to answer` },
	);
	const cfg = await fetch(`${baseUrl}/manifest.json`, { signal: AbortSignal.timeout(4000) }).catch(() => null);
	if (cfg?.ok) {
		const body = await cfg.json().catch(() => null);
		version = body?.version || null;
	}
	return version;
}

/** Home Assistant reports its own lifecycle on /api/config; wait for RUNNING. */
async function waitForRunning(baseUrl, token) {
	await waitFor(
		async () => {
			const res = await fetch(`${baseUrl}/api/config`, {
				headers: { authorization: `Bearer ${token}` },
				signal: AbortSignal.timeout(4000),
			}).catch(() => null);
			if (!res?.ok) return false;
			const body = await res.json().catch(() => null);
			return body?.state === 'RUNNING';
		},
		{ timeout: 180_000, label: `${baseUrl} to finish starting` },
	);
}

async function tokenWorks(baseUrl, token) {
	const res = await fetch(`${baseUrl}/api/`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
	return Boolean(res?.ok);
}

/**
 * Poll a condition to a deadline. Every wait in this harness is a wait for a
 * condition, never a sleep for a guessed duration: a sleep is the seed of every
 * flaky test this lane could grow.
 */
async function waitFor(condition, { timeout = 60_000, interval = 1000, label = 'condition' } = {}) {
	const deadline = Date.now() + timeout;
	let lastError = null;
	while (Date.now() < deadline) {
		try {
			if (await condition()) return true;
			lastError = null;
		} catch (err) {
			lastError = err;
		}
		await new Promise((r) => setTimeout(r, interval));
	}
	throw new Error(`timed out after ${Math.round(timeout / 1000)}s waiting for ${label}${lastError ? `: ${lastError.message}` : ''}`);
}

async function json(url, { method = 'GET', body, token, optional = false } = {}) {
	const headers = {};
	if (body) headers['content-type'] = 'application/json';
	if (token) headers.authorization = `Bearer ${token}`;
	const res = await fetch(url, { method, headers, body: body ? JSON.stringify(body) : undefined });
	if (!res.ok) {
		if (optional) return null;
		throw new Error(`${method} ${new URL(url).pathname} returned ${res.status}: ${(await res.text()).slice(0, 200)}`);
	}
	const text = await res.text();
	return text ? JSON.parse(text) : null;
}

function docker(args) {
	return new Promise((resolve, reject) => {
		const child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
		let out = '';
		let err = '';
		child.stdout.on('data', (d) => (out += d));
		child.stderr.on('data', (d) => (err += d));
		child.on('error', (e) => reject(new Error(`docker is not usable: ${e.message}`)));
		child.on('close', (code) => {
			if (code === 0) resolve(out.trim());
			else reject(new Error(`docker ${args[0]} failed: ${(err || out).trim().split('\n').slice(-3).join(' ')}`));
		});
	});
}

async function inspect(container) {
	const out = await docker(['inspect', container]).catch(() => null);
	if (!out) return null;
	const [info] = JSON.parse(out);
	return { running: Boolean(info?.State?.Running), labels: info?.Config?.Labels || {} };
}

/**
 * The guard that makes this safe to run on a machine full of other people's
 * Home Assistant containers. Nothing without our label is ever acted on.
 */
/**
 * Refuse to tear down a lane that somebody is still using.
 *
 * The label check below answers "did this harness make it", which is NOT the
 * same question as "is it mine". Every concurrent agent on this machine uses
 * this same harness, so a peer's house carries the identical label and
 * `--down --name <their lane>` sailed straight through it. That is not
 * hypothetical: on 2026-09-09 it removed a peer's seeded house out from under a
 * live run, and the label guard did exactly what it was written to do while it
 * happened.
 *
 * A lane in use is a lane that was handed out recently, which the ready path
 * records on every acquire. Tearing down your own finished lane still works
 * with no ceremony, because a finished lane goes quiet; taking one that is
 * still serving needs `--force` and says so.
 */
function assertNotInUse(inst, state, { force }) {
	if (force) return;
	const stamped = Date.parse(state?.lastAcquiredAt || '');
	if (!Number.isFinite(stamped)) return;
	const idleMs = Date.now() - stamped;
	if (idleMs >= IN_USE_MS) return;
	const mins = Math.max(1, Math.round(idleMs / 60_000));
	throw new Error(
		`refusing to remove "${inst.name}": a run took this house ${mins} minute(s) ago, and another agent on this machine may be inside it. Wait for it to go idle, or pass --force if you know it is yours.`,
	);
}

function assertOurs(info, container) {
	if (!info || info.labels?.[LABEL] !== '1') {
		throw new Error(
			`refusing to touch container "${container}": it was not created by this harness (missing ${LABEL} label). Pick another --name.`,
		);
	}
}

function freePort() {
	return new Promise((resolve, reject) => {
		const server = net.createServer();
		server.unref();
		server.on('error', reject);
		server.listen(0, '127.0.0.1', () => {
			const { port } = server.address();
			server.close(() => resolve(port));
		});
	});
}

function writeConfiguration(inst, { demo }) {
	// The three !include lines are not decoration. Home Assistant's scene, script
	// and automation config APIs write to these files, and without the includes
	// the write succeeds, the file appears, and no entity is ever created: a seed
	// that reports two scenes and produces none. That is exactly the silent
	// half-success this harness exists to stop.
	const lines = [
		'# Written by scripts/home-test-instance.mjs. Throwaway instance.',
		'default_config:',
		'logger:',
		'  default: warning',
		'scene: !include scenes.yaml',
		'script: !include scripts.yaml',
		'automation: !include automations.yaml',
	];
	if (demo) lines.push('demo:');
	fs.writeFileSync(path.join(inst.configDir, 'configuration.yaml'), `${lines.join('\n')}\n`);
	for (const store of ['scenes.yaml', 'scripts.yaml', 'automations.yaml']) {
		const file = path.join(inst.configDir, store);
		if (!fs.existsSync(file)) fs.writeFileSync(file, store === 'scripts.yaml' ? '{}\n' : '[]\n');
	}
}

function describeInstance(name, version) {
	const slug = String(name).replace(/[^a-z0-9-]/gi, '-').toLowerCase();
	return {
		name: slug,
		version,
		image: `${IMAGE}:${version}`,
		container: `three-ws-home-test-${slug}`,
		configDir: path.join(ROOT, `.ha-config-test-${slug}`),
	};
}

/**
 * An exclusive lock around one named instance, held for the whole up/onboard/
 * seed sequence. `mkdir` is the atomic primitive here: it either creates the
 * directory or fails, with no window between the two.
 *
 * The lock records WHO holds it, and that is the difference between a lock and
 * a fifteen-minute outage. Callers of this harness kill it on their own
 * timeouts (tests/_helpers/home-instance.js gives `--stop` 120 seconds), and a
 * killed process never reaches the `finally` below, so the directory outlives
 * it. Abandoning purely on age meant the next call on that lane sat in the wait
 * loop below until the stale lock aged out, then died on ITS caller's timeout
 * and left a fresh lock behind: one kill guaranteed the next several. It was
 * seen as `home-test-instance timed out after 120s` on a `--stop` that takes
 * seven seconds when it runs at all, which reads as a hung container and is a
 * dead process's leftovers.
 *
 * So the holder writes its pid, and a waiter asks the operating system whether
 * that process still exists. A dead holder's lock is reclaimed at once; a live
 * holder's is waited on exactly as before. Signal 0 is the standard "is this
 * pid alive" probe: it performs the permission check and delivers nothing.
 */
async function withLock(inst, fn) {
	const lock = `${inst.configDir}.lock`;
	const owner = path.join(lock, 'pid');
	const deadline = Date.now() + 900_000;
	for (;;) {
		try {
			fs.mkdirSync(lock);
			fs.writeFileSync(owner, `${process.pid}\n`);
			break;
		} catch (err) {
			if (err.code !== 'EEXIST') throw err;
			const holder = lockHolder(owner);
			// No pid file yet means the holder is between its mkdir and its write,
			// which is microseconds; anything else is a lock whose owner is gone.
			if (holder !== null && !isAlive(holder)) {
				log(`[lock] reclaiming the lock on "${inst.name}" from pid ${holder}, which is no longer running`);
				fs.rmSync(lock, { recursive: true, force: true });
				continue;
			}
			// Belt and braces for the pre-pid window and for a lock written by an
			// older copy of this script: nothing here outlasts a cold boot.
			const age = Date.now() - (fs.statSync(lock).mtimeMs || 0);
			if (age > 900_000) {
				fs.rmSync(lock, { recursive: true, force: true });
				continue;
			}
			if (Date.now() > deadline) throw new Error(`another run has held the lock on "${inst.name}" for 15 minutes`);
			log(`[lock] waiting for pid ${holder ?? 'unknown'} to finish with "${inst.name}"`);
			await new Promise((r) => setTimeout(r, 2000));
		}
	}
	// SIGKILL cannot be caught, which is why the pid check above exists; SIGTERM
	// and SIGINT can be, and releasing on them means the common case (a caller
	// asking politely first, a developer pressing ctrl-c) leaves nothing behind.
	const release = () => fs.rmSync(lock, { recursive: true, force: true });
	const onSignal = (signal) => {
		release();
		process.exit(signal === 'SIGINT' ? 130 : 143);
	};
	process.once('SIGTERM', onSignal);
	process.once('SIGINT', onSignal);
	try {
		return await fn();
	} finally {
		process.off('SIGTERM', onSignal);
		process.off('SIGINT', onSignal);
		release();
	}
}

/** The pid inside a lock directory, or null when it has not been written yet. */
function lockHolder(pidFile) {
	try {
		const pid = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
		return Number.isInteger(pid) && pid > 0 ? pid : null;
	} catch {
		return null;
	}
}

/** Whether a pid is a process this user could signal. Sends nothing. */
function isAlive(pid) {
	try {
		process.kill(pid, 0);
		return true;
	} catch (err) {
		// EPERM means it exists and belongs to somebody else, which still counts
		// as held. Only ESRCH is proof that nothing is there.
		return err.code === 'EPERM';
	}
}

function statePath(inst) {
	return path.join(inst.configDir, '.harness.json');
}

function readState(inst) {
	try {
		return JSON.parse(fs.readFileSync(statePath(inst), 'utf8'));
	} catch {
		return null;
	}
}

function requireState(inst) {
	const state = readState(inst);
	if (!state) throw new Error(`no instance named "${inst.name}" is up. Run --up first.`);
	return state;
}

function writeState(inst, state) {
	fs.mkdirSync(inst.configDir, { recursive: true });
	fs.writeFileSync(statePath(inst), `${JSON.stringify(state, null, '\t')}\n`);
	return state;
}

function parseArgs(args) {
	const out = { name: 'default', version: 'stable', json: false, env: false };
	for (let i = 0; i < args.length; i += 1) {
		const arg = args[i];
		if (arg === '--up') out.up = true;
		else if (arg === '--onboard') out.onboard = true;
		else if (arg === '--seed') out.seed = true;
		else if (arg === '--down') out.down = true;
		else if (arg === '--stop') out.stop = true;
		else if (arg === '--start') out.start = true;
		else if (arg === '--json') out.json = true;
		else if (arg === '--env') out.env = true;
		else if (arg === '--force') out.force = true;
		else if (arg === '--help' || arg === '-h') out.help = true;
		else if (arg === '--name') out.name = args[++i];
		else if (arg === '--version') out.version = args[++i];
		else throw new Error(`unknown argument "${arg}"`);
	}
	return out;
}

/** Single-quote for a POSIX shell, so an eval'd value cannot become a command. */
function shellQuote(value) {
	return `'${String(value).replace(/'/g, `'\\''`)}'`;
}

function usage() {
	console.log(`Usage: node scripts/home-test-instance.mjs [--up] [--onboard] [--seed] [--down] [options]

  --up                start a container on a free port and wait for readiness
  --onboard           complete onboarding and mint a long-lived access token
  --seed              demo entities, a floor, areas, scenes, mcp_server, an exposed lock
  --down              remove the container and its config directory
  --force             with --down, remove a house even if a run took it recently
  --stop              stop the container, keeping its config, token and entities
  --start             start a stopped container and wait until it answers
  --name <slug>       run more than one instance side by side (default: default)
  --version <tag>     Home Assistant image tag (default: stable)
  --json              machine-readable output for a test to consume
  --env               'export VAR=...' lines, for eval in a shell

Everything is idempotent. The usual call is:
  node scripts/home-test-instance.mjs --up --onboard --seed --json`);
}

await main();