amaran-light-cli 1.11.0 → 1.12.0

package/scripts/ble-config-probe.ts

@@ -0,0 +1,109 @@
+import { writeFileSync } from 'node:fs';
+import {
+  changeSubscription,
+  type MeshModel,
+  modelBindings,
+  readComposition,
+  subscriptions,
+} from '../src/ble/configuration.js';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { desktopDeviceKeys } from '../src/ble/desktop.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { brightnessPacket, type FixtureState } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+
+if (!process.argv[2]) throw new Error('Supply the matching Desktop database path; this probe is read-only');
+const config = desktopDeviceKeys(process.argv[2], loadMeshConfig());
+const crypto = new MeshCrypto(config.netKey, config.appKey);
+const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+const link = new MeshTransport(config, sequence, process.argv.includes('--debug'));
+const results: unknown[] = [];
+const capable: { key: string; address: number; model: MeshModel; groups: number[] }[] = [];
+const added: typeof capable = [];
+const original = new Map<number, FixtureState>();
+let discoveryFailed = false;
+try {
+  await link.connect();
+  for (const light of config.lights) {
+    try {
+      const data = await readComposition(link, light.address);
+      console.log(light.key, data);
+      const models = [];
+      for (const model of data.models.filter((item) => item.company !== undefined || item.model >= 0x1000)) {
+        const bindings = await modelBindings(link, light.address, model);
+        if (!bindings.includes(0)) continue;
+        const groups = await subscriptions(link, light.address, model);
+        models.push({ model, groups, bindings });
+        capable.push({ key: light.key, address: light.address, model, groups });
+      }
+      const phase = await link.configuration(
+        light.address,
+        Buffer.from([0x80, 0x15, 0, 0]),
+        (data) => data.length === 6 && data[0] === 0x80 && data[1] === 0x17
+      );
+      console.log(light.key, 'subscriptions', models, 'key refresh status', phase.toString('hex'));
+      results.push({
+        key: light.key,
+        composition: data,
+        subscriptions: models,
+        keyRefreshStatus: phase.toString('hex'),
+      });
+    } catch (error) {
+      discoveryFailed = true;
+      console.error(light.key, (error as Error).message);
+      results.push({ key: light.key, error: (error as Error).message });
+    }
+  }
+  if (process.argv.includes('--exercise')) {
+    const group = 0xce01;
+    if (discoveryFailed || !capable.length || capable.some((item) => item.groups.includes(group)))
+      throw new Error('Incomplete discovery or test group already in use');
+    for (const light of config.lights) {
+      const state = await link.readState(light.address);
+      if (state.intensity > 50) throw new Error('Use at most 5% output for this check');
+      original.set(light.address, state);
+    }
+    for (const item of capable.filter(
+      (item) => item.key !== 'front' && item.model.company === undefined && item.model.model === 0x1000
+    )) {
+      console.log('Adding temporary subscription', item.key, item.model);
+      added.push(item);
+      await changeSubscription(link, item.address, item.model, group, false);
+    }
+    await link.send(group, brightnessPacket(10));
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    for (const light of config.lights) {
+      const state = await link.readState(light.address);
+      const expected = light.key === 'front' ? original.get(light.address)?.intensity : 10;
+      if (state.intensity !== expected)
+        throw new Error(`Native group did not match ${light.key}: ${state.intensity}, expected ${expected}`);
+    }
+    console.log('Native subset group controlled desk/back without changing front');
+  }
+} finally {
+  const failures: string[] = [];
+  for (const [address, state] of original) {
+    try {
+      await link.send(address, brightnessPacket(state.intensity));
+      const restored = await link.readState(address);
+      if (restored.intensity !== state.intensity) failures.push(`Could not restore brightness at ${address}`);
+    } catch (error) {
+      failures.push(`${address}: ${error}`);
+    }
+  }
+  for (const item of added.reverse()) {
+    try {
+      await changeSubscription(link, item.address, item.model, 0xce01, true);
+    } catch (error) {
+      failures.push(`Remove test subscription ${item.address}: ${error}`);
+    }
+  }
+  await link.disconnect();
+  sequence.close();
+  if (failures.length) {
+    console.error(failures.join('\n'));
+    process.exitCode = 1;
+  }
+  writeFileSync(`artifacts/config-probe-${Date.now()}.json`, JSON.stringify(results, null, 2), { mode: 0o600 });
+}
+process.exit(process.exitCode ?? 0);

package/scripts/ble-effects-check.ts

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import { writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { COLOR_EFFECTS, WHITE_EFFECTS } from '../src/ble/effects.js';
+import { SavedStateSchema } from '../src/ble/library.js';
+import type { FixtureState } from '../src/ble/telink.js';
+import { captureWebcam } from './webcam.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const run = Date.now();
+const original: Record<string, FixtureState> = {};
+const results: unknown[] = [];
+const errors: string[] = [];
+let changed = false;
+async function request(key: string, action: string, body?: object) {
+  const response = await fetch(`${base}/lights/${key}/${action}`, {
+    method: body ? 'POST' : 'GET',
+    ...(body ? { body: JSON.stringify(body), headers: { 'content-type': 'application/json' } } : {}),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = z
+    .object({ ok: z.boolean(), result: z.unknown().optional(), error: z.string().optional() })
+    .parse(await response.json());
+  if (!response.ok || !data.ok) throw new Error(`${key}/${action}: ${data.error ?? response.status}`);
+  const state = SavedStateSchema.parse(data.result);
+  results.push({ key, action, body, state });
+  return state;
+}
+try {
+  for (const key of ['desk', 'front', 'back']) original[key] = await request(key, 'state');
+  assert.ok(
+    Object.values(original).every((state) => state.mode === 'cct'),
+    'Begin with a steady CCT setup'
+  );
+  changed = true;
+  for (const key of Object.keys(original)) await request(key, 'cct', { kelvin: 3200, brightness: 0 });
+  captureWebcam(`effects-${run}-dark-before`);
+  for (const key of Object.keys(original)) {
+    for (const name of key === 'back' ? COLOR_EFFECTS : WHITE_EFFECTS) {
+      const state = await request(key, 'effect', { name, brightness: 0, frequency: 1 });
+      assert.equal(state.effect, name);
+      assert.equal(state.intensity, 0);
+      assert.equal((await request(key, 'effect-speed', { value: 2 })).frequency, 2);
+      assert.equal((await request(key, 'effect-intensity', { value: 0 })).intensity, 0);
+      console.log(`${key}: ${name}, zero output, verified`);
+    }
+    if (key === 'back') {
+      for (const name of ['faulty-bulb', 'pulsing']) {
+        const state = await request(key, 'effect', { name, brightness: 0, frequency: 1, hue: 240, saturation: 80 });
+        assert.equal(state.hue, 240);
+        assert.equal(state.sat, 80);
+        assert.equal(state.intensity, 0);
+      }
+    }
+    await request(key, 'effect-stop', {});
+  }
+  captureWebcam(`effects-${run}-dark-after`);
+} catch (error) {
+  errors.push(String(error));
+} finally {
+  if (changed)
+    for (const [key, state] of Object.entries(original)) {
+      try {
+        await request(key, 'cct', {
+          kelvin: state.cct,
+          brightness: state.intensity / 10,
+          ...(key === 'back' ? { gm: state.gm } : {}),
+        });
+        await request(key, state.sleep ? 'off' : 'on', {});
+        const restored = await request(key, 'state');
+        for (const field of ['cct', 'sleep', 'intensity'] as const) assert.equal(restored[field], state[field]);
+        if (key === 'back') assert.equal(restored.gm, state.gm);
+      } catch (error) {
+        errors.push(`Restore ${key}: ${error}`);
+      }
+    }
+  writeFileSync(`artifacts/effects-${run}-results.json`, JSON.stringify({ original, results, errors }, null, 2), {
+    mode: 0o600,
+  });
+}
+if (errors.length) throw new Error(errors.join('\n'));
+console.log(`All native effect settings verified at zero output; artifacts/effects-${run}-results.json`);

package/scripts/ble-extended-probe.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { setTimeout as delay } from 'node:timers/promises';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { cctPacket, powerPacket } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+import { captureWebcam } from './webcam.js';
+
+const config = loadMeshConfig();
+const crypto = new MeshCrypto(config.netKey, config.appKey);
+const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+const transport = new MeshTransport(config, sequence, true);
+try {
+  await transport.connect();
+  const back = config.lights.find((light) => light.model === '150c');
+  if (!back) throw new Error('150c fixture not found');
+  const original = await transport.readState(back.address);
+  if (process.argv[2] === 'gm') {
+    try {
+      for (const gm of [-30, 0, 30]) {
+        await transport.send(back.address, cctPacket(3200, 10, gm));
+        await delay(300);
+        const state = await transport.readState(back.address);
+        console.log('G/M applied', state);
+        assert.equal(state.gm, gm);
+        assert.equal(state.cct, 3200);
+        assert.equal(state.intensity, 10);
+        console.log(captureWebcam(`gm-${gm < 0 ? 'minus' : 'plus'}-${Math.abs(gm)}-${Date.now()}`));
+      }
+    } finally {
+      await transport.send(back.address, cctPacket(original.cct ?? 3200, original.intensity, 0));
+      await delay(300);
+      await transport.send(back.address, powerPacket(!original.sleep));
+      console.log('Restored with corrected neutral tint', await transport.readState(back.address));
+    }
+  } else {
+    console.log(original);
+    for (const light of config.lights) console.log(light.key, await transport.readFan(light.address));
+  }
+} finally {
+  await transport.disconnect();
+  sequence.close();
+}
+process.exit(0);

package/scripts/ble-fan-check.ts

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { FanStateSchema, FanStatesSchema } from '../src/ble/fan.js';
+import { SavedStateSchema } from '../src/ble/library.js';
+import { FAN_MODES, parseFanMode } from '../src/ble/telink.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const run = Date.now();
+const records: unknown[] = [];
+const failures: string[] = [];
+let original: z.infer<typeof FanStatesSchema> | undefined;
+let group: string | undefined;
+let changed = false;
+const lights: Record<string, z.infer<typeof SavedStateSchema>> = {};
+
+async function request(route: string, body?: object, method = body ? 'POST' : 'GET') {
+  const response = await fetch(`${base}${route}`, {
+    method,
+    headers: { connection: 'close', ...(body ? { 'content-type': 'application/json' } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = z
+    .object({ ok: z.boolean(), result: z.unknown().optional(), error: z.string().optional() })
+    .parse(await response.json());
+  if (!response.ok || !data.ok) throw new Error(`${route}: ${data.error ?? response.status}`);
+  records.push({ route, body, result: data.result });
+  return data.result;
+}
+function cli(...args: string[]) {
+  const output = execFileSync(
+    process.execPath,
+    ['dist/cli.js', 'fan', ...args, '--backend', 'ble', '--url', base, '--json'],
+    {
+      encoding: 'utf8',
+      timeout: 60_000,
+    }
+  );
+  const data = FanStatesSchema.parse(JSON.parse(output));
+  records.push({ cli: args, result: data });
+  return data;
+}
+async function checkLighting() {
+  for (const [key, before] of Object.entries(lights)) {
+    const after = SavedStateSchema.parse(await request(`/lights/${key}/state`));
+    const { observedAt: _beforeTime, ...beforeSettings } = before;
+    const { observedAt: _afterTime, ...afterSettings } = after;
+    assert.deepEqual(afterSettings, beforeSettings, `${key}: fan control changed lighting`);
+  }
+}
+
+try {
+  original = FanStatesSchema.parse(await request('/fans'));
+  const keys = Object.keys(original.states);
+  for (const [key, state] of Object.entries(original.states)) {
+    parseFanMode(state.mode);
+    assert.notEqual(state.mode, FAN_MODES.manual, 'Cannot infer an original manual RPM setpoint for restoration');
+    assert.equal(state.highTemperature, false);
+    assert.ok(state.supported.smart && state.supported.medium);
+    lights[key] = SavedStateSchema.parse(await request(`/lights/${key}/state`));
+    assert.ok(
+      lights[key].intensity <= 50,
+      'Run fan checks at 5% brightness or less; do not stress-test thermal protection'
+    );
+  }
+  changed = true;
+  for (const state of Object.values(cli('mode', 'all', 'smart').states)) assert.equal(state.mode, 1);
+  for (const key of keys) {
+    const selected = cli('mode', key, 'medium').states[key];
+    assert.equal(selected.mode, 5);
+    assert.equal(selected.highTemperature, false);
+    assert.equal(selected.rpmStatus, selected.speed === 0 ? 'zero-reported' : 'rotation-reported');
+    assert.equal(FanStateSchema.parse(await request(`/lights/${key}/fan`)).mode, 5);
+  }
+  const savedGroup = z.object({ id: z.string() }).parse(await request('/groups', { name: `Fan verification ${run}` }));
+  group = savedGroup.id;
+  const members = [...new Set([keys[0], keys[keys.length - 1]])];
+  for (const member of members) await request(`/groups/${encodeURIComponent(group)}/members`, { member });
+  const grouped = cli('mode', group, 'smart');
+  assert.deepEqual(Object.keys(grouped.states).sort(), [...members].sort());
+  for (const state of Object.values(grouped.states)) assert.equal(state.mode, 1);
+  const deduplicated = FanStatesSchema.parse(await request('/fans', { targets: [group, members[0]], mode: 'medium' }));
+  assert.equal(Object.keys(deduplicated.states).length, members.length);
+  assert.equal(Object.keys(cli('info', group).states).length, members.length);
+  for (const mode of ['off', 'silent', 'low', 'manual']) {
+    await assert.rejects(
+      request('/fans', { targets: 'all', mode, ...(mode === 'manual' ? { rpm: 2200 } : {}) }),
+      /does not advertise/
+    );
+  }
+  await checkLighting();
+  if (process.argv.includes('--restart-service')) {
+    for (const action of ['stop', 'start'])
+      execFileSync(process.execPath, ['dist/cli.js', 'ble', 'service', action], { stdio: 'inherit', timeout: 100_000 });
+    for (const state of Object.values(cli('info').states))
+      assert.equal(state.mode, 5, 'Fan profile was reset on daemon restart');
+    await checkLighting();
+  }
+} catch (error) {
+  failures.push(String(error));
+} finally {
+  if (changed && original)
+    for (const [key, state] of Object.entries(original.states)) {
+      try {
+        const restored = FanStateSchema.parse(await request(`/lights/${key}/fan`, { mode: state.mode }));
+        assert.equal(restored.mode, state.mode);
+        assert.equal(restored.highTemperature, false);
+      } catch (error) {
+        failures.push(`Restore ${key}: ${error}`);
+      }
+    }
+  if (group) {
+    try {
+      await request(`/groups/${encodeURIComponent(group)}`, undefined, 'DELETE');
+    } catch (error) {
+      failures.push(`Group cleanup: ${error}`);
+    }
+  }
+  mkdirSync('artifacts/fan-safety', { recursive: true });
+  writeFileSync(
+    `artifacts/fan-safety/live-${run}.json`,
+    JSON.stringify({ original, lights, records, failures }, null, 2),
+    { mode: 0o600 }
+  );
+}
+if (failures.length) throw new Error(failures.join('\n'));
+console.log(`Fan profiles, CLI groups/all, telemetry and restoration passed: artifacts/fan-safety/live-${run}.json`);

package/scripts/ble-feature-probe.ts

@@ -0,0 +1,37 @@
+import { writeFileSync } from 'node:fs';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { packet } from '../src/ble/packets.js';
+import { decodeProductInfo } from '../src/ble/settings.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { MeshTransport } from '../src/ble/transport.js';
+
+const config = loadMeshConfig();
+const crypto = new MeshCrypto(config.netKey, config.appKey);
+const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+const link = new MeshTransport(config, sequence);
+const results: unknown[] = [];
+try {
+  await link.connect();
+  for (const light of config.lights) {
+    const info = await link.readPacket(light.address, packet(0), decodeProductInfo);
+    console.log(light.key, info);
+    let dimming: unknown;
+    try {
+      dimming = await link.readPacket(light.address, packet(8), (data) => {
+        if (data.length !== 10 || (data[9] & 127) !== 8) return undefined;
+        if ((data.subarray(1).reduce((sum, byte) => sum + byte, 0) & 255) !== data[0])
+          throw new Error('Invalid curve checksum');
+        return { mode: data[8], raw: data.toString('hex') };
+      });
+    } catch (error) {
+      dimming = { unavailable: (error as Error).message };
+    }
+    console.log(light.key, 'dimming query', dimming);
+    results.push({ key: light.key, info, dimming });
+  }
+} finally {
+  await link.disconnect();
+  sequence.close();
+  writeFileSync(`artifacts/feature-probe-${Date.now()}.json`, JSON.stringify(results, null, 2), { mode: 0o600 });
+}
+process.exit(0);

package/scripts/ble-followup-check.ts

@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { SavedStateSchema } from '../src/ble/library.js';
+import { FAN_MODES } from '../src/ble/telink.js';
+import { captureWebcam } from './webcam.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const run = Date.now();
+const records: unknown[] = [];
+const failures: string[] = [];
+const cleanup: string[] = [];
+let baseline: { id: string; states: Record<string, z.infer<typeof SavedStateSchema>> } | undefined;
+let group: string | undefined;
+let priorOverrides: Record<string, number> = {};
+
+async function request(route: string, body?: object, method = body ? 'POST' : 'GET') {
+  const response = await fetch(`${base}${route}`, {
+    method,
+    headers: { connection: 'close', ...(body ? { 'content-type': 'application/json' } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = z
+    .object({ ok: z.boolean(), result: z.unknown().optional(), error: z.string().optional() })
+    .parse(await response.json());
+  if (!response.ok || !data.ok) throw new Error(`${route}: ${data.error ?? response.status}`);
+  records.push({ route, body, result: data.result });
+  return data.result;
+}
+function cli(...args: string[]) {
+  const output = execFileSync(process.execPath, ['dist/cli.js', ...args, '--backend', 'ble', '--url', base], {
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+  records.push({ cli: args, output });
+  return output;
+}
+async function state(key: string) {
+  return SavedStateSchema.parse(await request(`/lights/${key}/state`));
+}
+const entry = z.object({ id: z.string() });
+function image(label: string) {
+  const filename = captureWebcam(`followup-${run}-${label}`);
+  const report = z
+    .object({
+      regions: z.array(
+        z.object({ name: z.string(), clippedFraction: z.number(), haloRgb: z.array(z.number()).optional() })
+      ),
+    })
+    .parse(JSON.parse(readFileSync(filename.replace(/\.png$/, '.json'), 'utf8')));
+  records.push({ camera: filename, regions: report.regions });
+  return report.regions;
+}
+
+try {
+  const remaining = z.record(z.number()).parse(await request('/overrides', { targets: 'all' }));
+  priorOverrides = Object.fromEntries(Object.entries(remaining).map(([key, ms]) => [key, ms ? Date.now() + ms : 0]));
+  for (const key of ['desk', 'front', 'back']) {
+    const before = await state(key);
+    assert.equal(before.mode, 'cct', 'Start these checks in steady CCT mode');
+    assert.ok(!before.sleep && before.intensity >= 10 && before.intensity <= 50, 'Begin with all fixtures on at 1-5%');
+  }
+  const regions = image('baseline');
+  for (const key of ['desk', 'front', 'back']) {
+    const region = regions.find((item) => item.name === key);
+    assert.ok(
+      region && region.clippedFraction > 0.25,
+      `${key}: camera region is not on the emitter; recalibrate before testing`
+    );
+  }
+  baseline = z
+    .object({ id: z.string(), states: z.record(SavedStateSchema) })
+    .parse(await request('/library/scenes', { name: `Followup baseline ${run}` }));
+  for (const key of Object.keys(baseline.states)) {
+    const info = z
+      .object({ cctMin: z.number(), cctMax: z.number(), protocolVersion: z.number() })
+      .parse(await request(`/lights/${key}/info`));
+    assert.equal(info.cctMin, key === 'back' ? 2500 : 2700);
+  }
+  group = entry.parse(await request('/groups', { name: `Followup ${run}` })).id;
+  for (const member of ['desk', 'back']) await request(`/groups/${encodeURIComponent(group)}/members`, { member });
+  cli('group', 'rename', group, `Followup renamed ${run}`);
+  assert.equal(
+    z.object({ name: z.string() }).parse(await request(`/groups/${encodeURIComponent(group)}`)).name,
+    `Followup renamed ${run}`
+  );
+  cli('ble', 'transition', 'cct', '2', '--targets', 'all', '--args', '{"kelvin":3200,"brightness":1}');
+  for (const key of ['desk', 'front', 'back']) assert.equal((await state(key)).cct, 3200);
+  cli('ble', 'transition', 'hsi', '2', '--targets', 'back', '--args', '{"hue":120,"saturation":100,"brightness":1}');
+  const green = image('green').find((region) => region.name === 'back')?.haloRgb;
+  assert.ok(green && green[1] - Math.max(green[0], green[2]) > 20);
+  assert.deepEqual(await request('/lights/back/auto-cct', { kelvin: 5600, brightness: 1 }), {
+    skipped: true,
+    reason: 'manual-override',
+  });
+  assert.equal((await state('back')).mode, 'hsi');
+  for (const key of ['desk', 'back'])
+    await request(`/lights/${key}/effect`, { name: 'pulsing', brightness: 0, frequency: 1 });
+  const triggered = z
+    .object({ triggerRequest: z.object({ sent: z.literal(true), eventConfirmed: z.literal(false) }) })
+    .parse(await request(`/lights/${encodeURIComponent(group)}/effect-trigger`, {}));
+  assert.equal(triggered.triggerRequest.eventConfirmed, false);
+  cli('effect', 'stop', group);
+  assert.equal((await state('desk')).mode, 'cct');
+  assert.equal((await state('back')).mode, 'hsi');
+  const preset = entry.parse(await request('/library/presets', { name: `Preset ${run}`, keys: ['back'] }));
+  cleanup.push(`/library/presets/${preset.id}`);
+  cli('preset', 'update', preset.id, '--name', `Preset updated ${run}`);
+  assert.equal(
+    z.object({ name: z.string() }).parse(await request(`/library/presets/${preset.id}`)).name,
+    `Preset updated ${run}`
+  );
+  const quickshot = entry.parse(await request('/library/quickshots', { name: `Quickshot ${run}` }));
+  cleanup.push(`/library/quickshots/${quickshot.id}`);
+  cli('quickshot', 'update', quickshot.id, '--name', `Quickshot updated ${run}`);
+  await request('/lights/back/fan', { mode: 'medium' });
+  cli('scene', 'recall', baseline.id, '--fade', '2');
+  for (const [key, expected] of Object.entries(baseline.states)) {
+    const actual = await state(key);
+    for (const field of ['mode', 'cct', 'intensity', 'sleep'] as const) assert.equal(actual[field], expected[field]);
+    if (expected.fan)
+      assert.equal(
+        z.object({ mode: z.number() }).parse(await request(`/lights/${key}/fan`)).mode,
+        FAN_MODES[expected.fan.mode]
+      );
+  }
+} catch (error) {
+  failures.push(String(error));
+} finally {
+  if (baseline) {
+    try {
+      await request(`/library/scenes/${baseline.id}/recall`, {});
+    } catch (error) {
+      failures.push(`Restore baseline: ${error}`);
+    }
+    cleanup.push(`/library/scenes/${baseline.id}`);
+  }
+  if (group) cleanup.push(`/groups/${encodeURIComponent(group)}`);
+  for (const route of cleanup) {
+    try {
+      await request(route, undefined, 'DELETE');
+    } catch (error) {
+      failures.push(`Cleanup ${route}: ${error}`);
+    }
+  }
+  if (!failures.length)
+    for (const [key, expires] of Object.entries(priorOverrides)) {
+      try {
+        await request('/overrides', { targets: [key], minutes: Math.max(0, (expires - Date.now()) / 60_000) });
+      } catch (error) {
+        failures.push(`Restore override ${key}: ${error}`);
+      }
+    }
+  writeFileSync(
+    `artifacts/followup-${run}-results.json`,
+    JSON.stringify({ baseline, priorOverrides, records, failures }, null, 2),
+    { mode: 0o600 }
+  );
+}
+if (failures.length) throw new Error(failures.join('\n'));
+console.log(
+  `Supported-control checks passed; lighting, fan profiles and overrides restored. artifacts/followup-${run}-results.json`
+);

package/scripts/ble-hardware-check.ts

@@ -0,0 +1,99 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { captureWebcam } from './webcam.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const run = Date.now();
+const results: object[] = [];
+const positions: Record<string, string> = { desk: 'desk', front: 'front', back: 'back' };
+
+async function request(key: string, action: string, body?: object) {
+  const response = await fetch(`${base}/lights/${encodeURIComponent(key)}/${action}`, {
+    method: body ? 'POST' : 'GET',
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = await response.json();
+  if (!response.ok || !data.ok) throw new Error(`${key} ${action}: ${data.error ?? response.status}`);
+  return data.result;
+}
+
+function image(label: string, key: string) {
+  const filename = captureWebcam(`ble-check-${run}-${label}`);
+  const metrics = JSON.parse(readFileSync(filename.replace(/\.png$/, '.json'), 'utf8'));
+  const region = metrics.regions.find((entry: { name: string }) => entry.name === positions[key]);
+  if (!region) throw new Error(`No camera ROI for ${key}`);
+  return {
+    filename,
+    rgb: region.rgb as number[],
+    haloRgb: region.haloRgb as number[] | undefined,
+    clippedFraction: region.clippedFraction as number,
+  };
+}
+
+const initial: Record<string, unknown> = {};
+const errors: unknown[] = [];
+try {
+  for (const key of Object.keys(positions)) initial[key] = await request(key, 'state');
+  writeFileSync(`artifacts/ble-check-${run}-initial.json`, JSON.stringify(initial, null, 2), { mode: 0o600 });
+  for (const key of Object.keys(positions)) await request(key, 'off', {});
+  for (const key of Object.keys(positions)) {
+    const dark = image(`${key}-off`, key);
+    await request(key, 'cct', { kelvin: 3200, brightness: 1 });
+    await request(key, 'on', {});
+    for (const kelvin of [3200, 6500]) {
+      const state = await request(key, 'cct', { kelvin, brightness: 1 });
+      await delay(500);
+      const optical = image(`${key}-${kelvin}-1pct`, key);
+      const difference = optical.rgb.reduce((sum, value, i) => sum + value - dark.rgb[i], 0) / 3;
+      if (difference < 40) throw new Error(`${key}: camera did not confirm illumination (difference ${difference})`);
+      results.push({ key, action: 'cct', requested: kelvin, state, optical, opticalOnDifference: difference });
+    }
+    for (const value of [0, 1, 2]) {
+      const state = await request(key, 'brightness', { value });
+      results.push({
+        key,
+        action: 'brightness',
+        requested: value,
+        state,
+        optical: image(`${key}-${value}pct`, key),
+      });
+    }
+    const state = await request(key, 'off', {});
+    results.push({ key, action: 'off', state, optical: image(`${key}-off-after`, key) });
+  }
+  await request('back', 'on', {});
+  for (const [hue, channel] of [
+    [0, 0],
+    [120, 1],
+    [240, 2],
+  ]) {
+    const state = await request('back', 'hsi', { hue, saturation: 100, brightness: 1 });
+    await delay(500);
+    const optical = image(`back-hue-${hue}`, 'back');
+    const color = optical.haloRgb;
+    if (!color || color[channel] - Math.max(...color.filter((_, i) => i !== channel)) < 20)
+      throw new Error(`Camera did not confirm hue ${hue}: halo RGB ${color}`);
+    results.push({ key: 'back', action: 'hsi', requested: hue, state, optical });
+  }
+} catch (error) {
+  errors.push(error);
+} finally {
+  const failures: string[] = [];
+  for (const key of Object.keys(positions)) {
+    try {
+      await request(key, 'off', {});
+    } catch (error) {
+      failures.push(`${key}: ${(error as Error).message}`);
+    }
+  }
+  writeFileSync(
+    `artifacts/ble-check-${run}-results.json`,
+    JSON.stringify({ results, errors: errors.map(String), shutdownFailures: failures }, null, 2),
+    { mode: 0o600 }
+  );
+  if (failures.length) errors.push(new Error(`Could not confirm lights off: ${failures.join('; ')}`));
+}
+if (errors.length) throw new AggregateError(errors, 'Hardware verification failed');
+console.log(`Hardware feedback checks completed: ${results.length} verified states with local images.`);