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.

16.6 KB
Raw Blame
#!/usr/bin/env node
/**
 * The home lane's correctness depends on a third party's monthly release.
 *
 * Home Assistant ships every month and moves WebSocket commands, config-flow
 * schemas and entity attributes between releases. Nothing used to notice: the
 * lane's live tests ran against whatever `stable` happened to be that day, so a
 * command renamed in the next release would first be reported by a user whose
 * front door stopped answering. This runs the lane's real client library
 * against every release we claim to support and prints what each one does.
 *
 *   node scripts/home-version-matrix.mjs                  # the derived version set
 *   node scripts/home-version-matrix.mjs --versions 2026.8,2026.7
 *   node scripts/home-version-matrix.mjs --keep-images    # skip the disk reclaim
 *   node scripts/home-version-matrix.mjs --check         # is the published table still the measured one
 *   node scripts/home-version-matrix.mjs --sync-doc      # rewrite the published table from the last run
 *
 * The version set is DERIVED, never hardcoded: Home Assistant's own analytics
 * (https://analytics.home-assistant.io/data.json, ~676k opted-in installs)
 * carries the live install share per release, and the set is the current
 * stable, the two releases before it, and the oldest release still in
 * contiguous wide use at or above one percent of installs. That last one is the
 * supported floor, and it moves on its own as the world upgrades.
 *
 * Each version is pulled, tested and removed one at a time, because four Home
 * Assistant images is thirteen gigabytes and this machine does not have it.
 */

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

import { connectHomeMcp, ERR, flattenEntities, HomeBridge } from '../packages/home-bridge/src/index.js';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const HARNESS = path.join(ROOT, 'scripts', 'home-test-instance.mjs');
const IMAGE = 'ghcr.io/home-assistant/home-assistant';
const ANALYTICS = 'https://analytics.home-assistant.io/data.json';
const OUT_JSON = path.join(ROOT, 'docs', 'ops', 'home-version-matrix.json');
const OUT_DOC = path.join(ROOT, 'docs', 'smart-home.md');
const DOC_START = '<!-- home-version-matrix:start -->';
const DOC_END = '<!-- home-version-matrix:end -->';

/**
 * The entry point sits below every declaration it uses. A top-level driver
 * above a `const` helper reads it in the temporal dead zone and throws, which
 * is the same trap `npm run check:tdz-bootstrap` exists to catch in browser
 * modules.
 */
async function main() {
	const args = parse(process.argv.slice(2));

	// --check and --sync-doc read the last run's JSON instead of pulling four
	// Home Assistant images. They exist because the published table drifted from
	// the measurements once already: the runner wrote the JSON and left the
	// markdown to a human, and by the next run the doc claimed shares and entity
	// counts no release had ever reported.
	if (args.check || args.syncDoc) {
		const report = readReport();
		const written = syncDoc(report, { write: args.syncDoc });
		if (args.syncDoc) console.error(`[matrix] ${written ? 'updated' : 'left unchanged'} ${path.relative(ROOT, OUT_DOC)}`);
		else if (!written) console.error(`[matrix] ${path.relative(ROOT, OUT_DOC)} matches ${path.relative(ROOT, OUT_JSON)}`);
		else {
			console.error(`[matrix] ${path.relative(ROOT, OUT_DOC)} is stale. Run: npm run home:matrix:sync`);
			process.exitCode = 1;
		}
		return;
	}

	const versions = args.versions || (await deriveVersions());
	console.error(`[matrix] testing ${versions.map((v) => v.tag).join(', ')}`);

	const results = [];
	for (const version of versions) {
		results.push(await runVersion(version));
		if (!args.keepImages) await reclaim(version.tag);
	}

	const report = { measuredAt: new Date().toISOString(), source: ANALYTICS, results };
	fs.mkdirSync(path.dirname(OUT_JSON), { recursive: true });
	fs.writeFileSync(OUT_JSON, `${JSON.stringify(report, null, '\t')}\n`);
	syncDoc(report, { write: true });

	console.log(renderTable(results));
	console.error(`\n[matrix] wrote ${path.relative(ROOT, OUT_JSON)} and ${path.relative(ROOT, OUT_DOC)}`);

	// A version that cannot connect at all is the finding this runner exists to
	// surface, so it fails the command rather than printing a quiet FAIL cell.
	const broken = results.filter((r) => !r.cells.connect?.ok);
	process.exitCode = broken.length && !args.allowFailures ? 1 : 0;
}

// ---------------------------------------------------------------- versions

/**
 * The releases to hold, read from Home Assistant's live install share rather
 * than from a list somebody typed six months ago.
 */
async function deriveVersions() {
	const res = await fetch(ANALYTICS, { signal: AbortSignal.timeout(30_000) });
	if (!res.ok) throw new Error(`${ANALYTICS} returned ${res.status}`);
	const body = await res.json();
	const raw = body?.current?.versions || {};
	const total = Object.values(raw).reduce((a, b) => a + b, 0);
	if (!total) throw new Error('Home Assistant analytics returned no version histogram.');

	// Patch releases within a month are the same code for our purposes: what
	// moves a WebSocket command is the monthly release.
	const byMinor = new Map();
	for (const [full, count] of Object.entries(raw)) {
		const [year, month] = full.split('.');
		if (!/^\d+$/.test(year) || !/^\d+$/.test(month)) continue;
		const key = `${year}.${month}`;
		byMinor.set(key, (byMinor.get(key) || 0) + count);
	}
	const ordered = [...byMinor.entries()]
		.map(([tag, count]) => ({ tag, count, share: (100 * count) / total }))
		.sort((a, b) => compareVersions(b.tag, a.tag));

	// The newest release with a real user base is "current": the very newest tag
	// in the histogram is often a handful of early upgraders on a release that
	// is barely out.
	const startIndex = ordered.findIndex((v) => v.share >= 1);
	const recent = ordered.slice(startIndex, startIndex + 3);

	// The floor is the end of the CONTIGUOUS run at or above one percent. An
	// isolated old release above the line is a pinned island, not a version the
	// world is still on, and treating it as the floor would overstate support.
	let floor = recent[recent.length - 1];
	for (let i = startIndex; i < ordered.length; i += 1) {
		if (ordered[i].share < 1) break;
		floor = ordered[i];
	}

	const picked = [...recent];
	if (!picked.some((v) => v.tag === floor.tag)) picked.push(floor);
	return picked.map((v, i) => ({
		tag: v.tag,
		share: v.share,
		role: i === 0 ? 'current stable' : v.tag === floor.tag && i === picked.length - 1 ? 'oldest in wide use' : 'previous release',
		installs: v.count,
	}));
}

function compareVersions(a, b) {
	const pa = a.split('.').map(Number);
	const pb = b.split('.').map(Number);
	for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
		const diff = (pa[i] || 0) - (pb[i] || 0);
		if (diff) return diff;
	}
	return 0;
}

// ---------------------------------------------------------------- one version

async function runVersion(version) {
	const name = `mx-${version.tag.replace(/\./g, '-')}`;
	const cells = blankCells();
	const notes = [];
	let instance = null;

	console.error(`\n[matrix] ${version.tag} (${version.role}, ${version.share.toFixed(2)}% of installs)`);
	try {
		instance = await harness(['--up', '--onboard', '--seed', '--json', '--name', name, '--version', version.tag]);
		if (!instance.ok) throw new Error(instance.error);
		if (instance.seed?.exposeCommand) notes.push(`exposes via \`${instance.seed.exposeCommand}\``);
		if (instance.seed && !instance.seed.scenes) notes.push('the scene config API created nothing');
		await probe(instance, cells, notes);
	} catch (err) {
		// A version that cannot even be built is a finding, not a crash.
		if (!cells.connect) cells.connect = fail(err.message);
		notes.push(err.message);
	} finally {
		await harness(['--down', '--json', '--name', name]).catch(() => {});
	}

	return { ...version, haVersion: instance?.haVersion || null, cells, notes };
}

/** Every capability the lane depends on, exercised through the real library. */
async function probe(instance, cells, notes) {
	const { baseUrl, token } = instance;
	const home = new HomeBridge({ baseUrl, token });

	await home.connect();
	cells.connect = ok(home.haVersion || instance.haVersion || '');

	const { floors, areas, devices, entities } = home.registries;
	cells.registries = floors.length && areas.length && entities.length
		? ok(`${floors.length}f/${areas.length}a/${devices.length}d/${entities.length}e`)
		: fail(`${floors.length}f/${areas.length}a/${devices.length}d/${entities.length}e`);
	if (!floors.length) notes.push('no floor registry: the 3D scene renders a single level');

	try {
		const light = Object.keys(home.states).find((id) => id.startsWith('light.'));
		if (!light) throw new Error('no light entity in the seeded house');
		const before = home.states[light].state;
		await home.call('light', 'toggle', { entity_id: light });
		await until(() => home.states[light].state !== before, 20_000, `${light} to change on the socket`);
		cells.stream = ok('push');
	} catch (err) {
		cells.stream = fail(err.message);
	}

	try {
		const lock = Object.keys(home.states).find((id) => id.startsWith('lock.') && home.states[id].state === 'locked');
		if (!lock) throw new Error('no locked door in the seeded house');
		let refused = false;
		await home.call('lock', 'unlock', { entity_id: lock }).catch((err) => (refused = err.code === ERR.NEEDS_CONFIRMATION));
		if (!refused) throw new Error('the gate did not refuse an unconfirmed unlock');
		if ((await readState(instance, lock)) !== 'locked') throw new Error('the door moved on a refused call');

		await home.call('lock', 'unlock', { entity_id: lock }, { confirmed: true });
		await untilState(instance, lock, ['unlocked', 'unlocking', 'open', 'opening']);
		await home.call('lock', 'lock', { entity_id: lock });
		await untilState(instance, lock, ['locked', 'locking']);
		cells.call = ok('gated');
	} catch (err) {
		cells.call = fail(err.message);
	}

	try {
		const { match } = await home.activate('good night', { dryRun: true });
		cells.scenes = match ? ok(match.kind) : fail('no scene matched "good night"');
	} catch (err) {
		cells.scenes = fail(err.message);
	}

	try {
		const mcp = await connectHomeMcp({
			baseUrl,
			token,
			entities: () => flattenEntities(home.graph),
			isAllowed: () => false,
		});
		cells.mcp = ok(`${mcp.tools.length} tools`);
		await mcp.close();
	} catch (err) {
		// NO_MCP on a release that predates the integration is the correct
		// answer, not a failure: the MCP channel is an upgrade, never a
		// requirement, and the library already degrades to the WebSocket channel.
		cells.mcp = err.code === ERR.NO_MCP ? { ok: true, note: 'absent', degraded: true } : fail(err.message);
		if (err.code === ERR.NO_MCP) notes.push('no mcp_server: the WebSocket channel carries the house alone');
	}

	home.close();
}

// ---------------------------------------------------------------- the doc

/**
 * The published table, rewritten from the measurements.
 *
 * `docs/smart-home.md` is where a developer actually reads which releases we
 * hold, so the runner owns that section rather than trusting someone to
 * transcribe a JSON file by hand. Returns whether the file's content differs
 * from what the report says it should be, which is what `--check` reports and
 * `--sync-doc` acts on.
 */
function syncDoc(report, { write }) {
	const doc = fs.readFileSync(OUT_DOC, 'utf8');
	const start = doc.indexOf(DOC_START);
	const end = doc.indexOf(DOC_END);
	if (start < 0 || end < 0) throw new Error(`${path.relative(ROOT, OUT_DOC)} is missing the ${DOC_START} / ${DOC_END} markers.`);

	const body = renderDocSection(report);
	const next = `${doc.slice(0, start)}${DOC_START}\n${body}\n${doc.slice(end)}`;
	const changed = next !== doc;
	if (changed && write) fs.writeFileSync(OUT_DOC, next);
	return changed;
}

function renderDocSection(report) {
	const measured = report.measuredAt.slice(0, 10);
	const floor = report.results.reduce((oldest, r) => (compareVersions(r.tag, oldest.tag) < 0 ? r : oldest), report.results[0]);
	const broken = report.results.filter((r) => Object.values(r.cells).some((c) => c && !c.ok));

	const range = broken.length
		? `**Supported range: ${floor.tag} and newer, with exceptions.** ${broken.map((r) => `\`${r.tag}\` fails ${Object.entries(r.cells).filter(([, c]) => c && !c.ok).map(([k]) => k).join(', ')}`).join('; ')}.`
		: `**Supported range: ${floor.tag} and newer.** Every capability the platform depends on works across it. The floor is where install share falls below one percent, not where the code stops working; nothing was found that a ${floor.tag} house cannot do.`;

	return [
		`Measured ${measured}, by \`npm run home:matrix\`. This table is written by the runner from`,
		`[\`docs/ops/home-version-matrix.json\`](ops/home-version-matrix.json); do not edit it by hand.`,
		'',
		renderTable(report.results),
		'',
		range,
	].join('\n');
}

function readReport() {
	if (!fs.existsSync(OUT_JSON)) throw new Error(`${path.relative(ROOT, OUT_JSON)} does not exist. Run: npm run home:matrix`);
	return JSON.parse(fs.readFileSync(OUT_JSON, 'utf8'));
}

// ---------------------------------------------------------------- rendering

function renderTable(rows) {
	const head = ['Version', 'Share', 'Connect', 'Registries', 'State stream', 'Service call', 'Scenes', '`mcp_server`', 'Notes'];
	const lines = [`| ${head.join(' | ')} |`, `|${head.map(() => '---').join('|')}|`];
	for (const r of rows) {
		lines.push(
			`| \`${r.tag}\` (${r.role}) | ${r.share.toFixed(2)}% | ${cell(r.cells.connect)} | ${cell(r.cells.registries)} | ${cell(r.cells.stream)} | ${cell(r.cells.call)} | ${cell(r.cells.scenes)} | ${cell(r.cells.mcp)} | ${r.notes.length ? r.notes.join('; ') : 'none'} |`,
		);
	}
	return lines.join('\n');
}

function cell(value) {
	if (!value) return 'not run';
	const mark = value.ok ? (value.degraded ? 'degraded' : 'pass') : 'FAIL';
	return value.note ? `${mark} (${value.note})` : mark;
}

function blankCells() {
	return { connect: null, registries: null, stream: null, call: null, scenes: null, mcp: null };
}

function ok(note) {
	return { ok: true, note };
}

function fail(note) {
	return { ok: false, note: String(note).slice(0, 120) };
}

// ---------------------------------------------------------------- plumbing

async function readState(instance, entityId) {
	const res = await fetch(`${instance.baseUrl}/api/states/${encodeURIComponent(entityId)}`, {
		headers: { authorization: `Bearer ${instance.token}` },
		signal: AbortSignal.timeout(15_000),
	});
	if (!res.ok) throw new Error(`GET /api/states/${entityId} returned ${res.status}`);
	return (await res.json()).state;
}

function untilState(instance, entityId, expected, timeout = 25_000) {
	const wanted = new Set(expected);
	return until(async () => wanted.has(await readState(instance, entityId)), timeout, `${entityId} to reach ${expected.join('/')}`);
}

async function until(condition, timeout, label) {
	const deadline = Date.now() + timeout;
	while (Date.now() < deadline) {
		// The condition may be sync (a socket-backed state read) or async (an HTTP
		// read), and both must be tolerated without the caller thinking about it.
		const met = await Promise.resolve()
			.then(condition)
			.catch(() => false);
		if (met) return true;
		await new Promise((r) => setTimeout(r, 250));
	}
	throw new Error(`timed out waiting for ${label}`);
}

function harness(argv) {
	return new Promise((resolve, reject) => {
		const child = spawn(process.execPath, [HARNESS, ...argv], { cwd: ROOT, stdio: ['ignore', 'pipe', 'inherit'] });
		let out = '';
		child.stdout.on('data', (d) => (out += d));
		child.on('error', reject);
		child.on('close', () => {
			try {
				resolve(JSON.parse(out));
			} catch {
				reject(new Error(`home-test-instance produced no JSON for ${argv.join(' ')}`));
			}
		});
	});
}

/**
 * Four Home Assistant images do not fit on this disk, so each one goes as soon
 * as its column is filled in.
 */
async function reclaim(tag) {
	await new Promise((resolve) => {
		const child = spawn('docker', ['image', 'rm', `${IMAGE}:${tag}`], { stdio: 'ignore' });
		child.on('error', resolve);
		child.on('close', resolve);
	});
}

function parse(argv) {
	const out = { keepImages: false, allowFailures: false, check: false, syncDoc: false };
	for (let i = 0; i < argv.length; i += 1) {
		if (argv[i] === '--versions') {
			out.versions = argv[++i]
				.split(',')
				.map((tag) => ({ tag: tag.trim(), share: 0, role: 'requested', installs: 0 }));
		} else if (argv[i] === '--keep-images') out.keepImages = true;
		else if (argv[i] === '--allow-failures') out.allowFailures = true;
		else if (argv[i] === '--check') out.check = true;
		else if (argv[i] === '--sync-doc') out.syncDoc = true;
		else throw new Error(`unknown argument "${argv[i]}"`);
	}
	return out;
}

await main();