amaran-light-cli 1.10.0 → 1.12.0

package/scripts/ble-cli-check.ts

@@ -0,0 +1,129 @@
+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';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const Schema = z.object({
+  prefix: z.string(),
+  initial: z.record(SavedStateSchema),
+  grouped: z.record(SavedStateSchema),
+});
+function cli(...args: string[]) {
+  const separator = args.indexOf('--');
+  const flags = ['--backend', 'ble', '--url', base];
+  const command =
+    separator < 0 ? [...args, ...flags] : [...args.slice(0, separator), ...flags, ...args.slice(separator)];
+  return execFileSync(process.execPath, ['dist/cli.js', ...command], { encoding: 'utf8', timeout: 60_000 });
+}
+async function snapshot() {
+  const states: z.infer<typeof Schema>['initial'] = {};
+  for (const key of ['desk', 'front', 'back']) {
+    const response = await fetch(`${base}/lights/${key}/state`, { signal: AbortSignal.timeout(15_000) });
+    const data = z.object({ ok: z.literal(true), result: SavedStateSchema }).parse(await response.json());
+    states[key] = data.result;
+  }
+  return states;
+}
+function equal(actual: z.infer<typeof Schema>['initial'], expected: z.infer<typeof Schema>['initial']) {
+  for (const key of Object.keys(expected)) {
+    for (const field of ['mode', 'cct', 'intensity', 'sleep'] as const)
+      assert.equal(actual[key][field], expected[key][field]);
+    if (key === 'back') assert.equal(actual[key].gm, expected[key].gm);
+  }
+}
+const phase = process.argv[2];
+if (phase === 'prepare') {
+  const prefix = `CLI verification ${Date.now()}`;
+  const initial = await snapshot();
+  assert.ok(Object.values(initial).every((state) => state.mode === 'cct'));
+  const filename = `artifacts/cli-check-${Date.now()}.json`;
+  writeFileSync(filename, JSON.stringify({ prefix, initial, grouped: initial }, null, 2), { mode: 0o600 });
+  const created: [string, string][] = [];
+  try {
+    cli('scene', 'save', `${prefix} scene`);
+    created.push(['scene', `${prefix} scene`]);
+    cli('preset', 'save', 'back', `${prefix} preset`);
+    created.push(['preset', `${prefix} preset`]);
+    cli('group', 'create', `${prefix} group`);
+    created.push(['group', `${prefix} group`]);
+    cli('group', 'add', `${prefix} group`, 'desk');
+    cli('group', 'add', `${prefix} group`, 'front');
+    cli('intensity', '1', `${prefix} group`);
+    cli('intensity', '1', `${prefix} group`, '--relative');
+    cli('cct', '100', `${prefix} group`, '--relative');
+    const grouped = await snapshot();
+    assert.equal(grouped.desk.intensity, 20);
+    assert.equal(grouped.front.intensity, 20);
+    assert.equal(grouped.back.intensity, initial.back.intensity);
+    assert.equal(grouped.desk.cct, (initial.desk.cct ?? 0) + 100);
+    const status = cli('status', `${prefix} group`);
+    assert.ok(status.includes('Status for desk') && status.includes('Status for front') && !status.includes('Unknown'));
+    cli('quickshot', 'save', `${prefix} quickshot`);
+    created.push(['quickshot', `${prefix} quickshot`]);
+    cli('ble', 'gm', 'back', '--', '-30');
+    assert.equal((await snapshot()).back.gm, -30);
+    writeFileSync(filename, JSON.stringify({ prefix, initial, grouped }, null, 2), { mode: 0o600 });
+    console.log(`Prepared persistent CLI checks: ${filename}`);
+  } catch (error) {
+    const failures: unknown[] = [error];
+    if (created.some(([kind]) => kind === 'scene')) {
+      try {
+        cli('scene', 'recall', `${prefix} scene`);
+        equal(await snapshot(), initial);
+      } catch (restoration) {
+        failures.push(restoration);
+      }
+    }
+    for (const [kind, name] of created.reverse()) {
+      try {
+        cli(kind, 'delete', name);
+      } catch (cleanup) {
+        failures.push(cleanup);
+      }
+    }
+    throw new AggregateError(failures, `CLI preparation failed; recovery snapshot: ${filename}`);
+  }
+} else if (phase === 'verify' && process.argv[3]) {
+  const filename = process.argv[3];
+  const { prefix, initial, grouped } = Schema.parse(JSON.parse(readFileSync(filename, 'utf8')));
+  const errors: unknown[] = [];
+  try {
+    assert.ok(cli('group', 'list').includes(`${prefix} group`));
+    assert.ok(cli('preset', 'list').includes(`${prefix} preset`));
+    assert.ok(cli('quickshot', 'list').includes(`${prefix} quickshot`));
+    cli('preset', 'recall', 'back', `${prefix} preset`);
+    assert.equal((await snapshot()).back.gm, initial.back.gm);
+    cli('scene', 'recall', `${prefix} scene`);
+    equal(await snapshot(), initial);
+    cli('intensity', '1', 'all');
+    cli('quickshot', 'set', `${prefix} quickshot`);
+    equal(await snapshot(), grouped);
+  } catch (error) {
+    errors.push(error);
+  } finally {
+    try {
+      cli('scene', 'recall', `${prefix} scene`);
+      equal(await snapshot(), initial);
+    } catch (error) {
+      errors.push(error);
+    }
+    for (const [kind, name] of [
+      ['preset', 'preset'],
+      ['quickshot', 'quickshot'],
+      ['group', 'group'],
+      ['scene', 'scene'],
+    ]) {
+      try {
+        cli(kind, 'delete', `${prefix} ${name}`);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+  }
+  if (errors.length) throw new AggregateError(errors, 'CLI persistence checks or restoration failed');
+  console.log(
+    'CLI groups, tint, relative controls, presets, scenes and quickshots survived restart; initial lighting restored.'
+  );
+} else throw new Error('Use prepare, restart the daemon, then verify <manifest>');

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);