@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/pioneer/pioneer.classes.client.ts

@@ -1,462 +1,166 @@
 import * as plugins from '../../plugins.js';
-import { SimpleLocalClient, SimpleLocalMapper, type ISimpleLocalEntitySnapshot, type IServiceCallRequest, type IServiceCallResult } from '../../core/index.js';
-import type { IPioneerConfig, IPioneerSnapshot } from './pioneer.types.js';
-import { pioneerDefaultName, pioneerDefaultPort, pioneerMaxSourceNumbers, pioneerMaxVolume, pioneerProfile } from './pioneer.types.js';
-
-export class PioneerClient extends SimpleLocalClient<IPioneerConfig> {
-  private liveSnapshot?: IPioneerSnapshot;
-
-  constructor(private readonly configArg: IPioneerConfig) {
-    super(pioneerProfile, configArg);
-  }
-
-  public override async getSnapshot(forceRefreshArg = false): Promise<IPioneerSnapshot> {
-    if (!forceRefreshArg && this.liveSnapshot) {
-      return SimpleLocalMapper.clone(this.liveSnapshot);
-    }
-
-    if (this.shouldUseNativeTelnet(forceRefreshArg)) {
-      try {
-        this.liveSnapshot = await this.fetchSnapshot();
-      } catch (errorArg) {
-        this.liveSnapshot = this.createOfflineSnapshot(errorMessage(errorArg));
-      }
-      return SimpleLocalMapper.clone(this.liveSnapshot);
-    }
-
-    this.liveSnapshot = await super.getSnapshot(forceRefreshArg) as IPioneerSnapshot;
-    return SimpleLocalMapper.clone(this.liveSnapshot);
-  }
-
-  public override async refresh(): Promise<IServiceCallResult> {
-    this.liveSnapshot = undefined;
-    const snapshot = await this.getSnapshot(true);
-    const success = snapshot.online && !snapshot.error;
-    return { success, error: success ? undefined : snapshot.error, data: snapshot };
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IPioneerConfig, IPioneerEffectResult, IPioneerSnapshot, TPioneerControl } from './pioneer.types.js';
+import { normalizePioneerConfig, validatePioneerControl } from './pioneer.validation.js';
+
+/** Home admission and caller work belong here; the published foundation owns the wire. */
+export class PioneerClient {
+  public readonly config: ReturnType<typeof normalizePioneerConfig>;
+  private readonly protocol: plugins.ecobridgeDeviceManager.PioneerProtocol;
+  private readonly admission = new NativeHomeAdmission('pioneer');
+  private readonly context: INativeAdmissionContext;
+  private readonly lifetime = new AbortController();
+  private operationTail: Promise<void> = Promise.resolve();
+  private pendingOperations = 0;
+  private startPromise?: Promise<IPioneerSnapshot>;
+  private snapshot?: IPioneerSnapshot;
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
+
+  public constructor(config: IPioneerConfig, context: INativeIntegrationSetupContext) {
+    this.config = normalizePioneerConfig(config);
+    this.context = this.admission.admit(context, this.config.homeId);
+    this.protocol = new plugins.ecobridgeDeviceManager.PioneerProtocol({
+      address: this.config.host, descriptionUrl: this.config.descriptionUrl, expectedUdn: this.config.expectedUdn,
+      expectedModel: this.config.model, allowUnencryptedLan: this.config.allowUnencryptedLan,
+      maximumVolumeRaw: this.config.maximumVolumeRaw, port: this.config.port, timeoutMs: this.config.timeoutMs,
+      maxPendingOperations: this.config.maxPendingOperations, maxDescriptionBytes: this.config.maxDescriptionBytes,
+      maxFrameBytes: this.config.maxFrameBytes,
+    });
   }
 
-  public override async execute(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (this.configArg.client?.execute || this.configArg.commandExecutor || !this.endpoint()) {
-      return super.execute(requestArg);
-    }
-
-    try {
-      const command = await this.commandForService(requestArg);
-      const endpoint = this.requireEndpoint();
-      await sendPioneerCommand(endpoint, command, this.configArg.timeoutMs || 3000);
-      this.liveSnapshot = undefined;
-      return { success: true, data: { command } };
-    } catch (errorArg) {
-      return { success: false, error: errorMessage(errorArg) };
-    }
+  public isHealthy(): boolean {
+    try { this.assertOpen(); return this.snapshot !== undefined; } catch { return false; }
   }
 
-  private shouldUseNativeTelnet(forceRefreshArg: boolean): boolean {
-    if (!this.endpoint() || this.configArg.client || this.configArg.snapshotProvider) {
-      return false;
+  public start(signal?: AbortSignal): Promise<IPioneerSnapshot> {
+    try { this.assertOpen(); this.assertSignal(signal); } catch (error) { return Promise.reject(error); }
+    if (!this.startPromise) {
+      this.startPromise = this.run(async (operationSignal, timeoutMs) => this.observe(await this.protocol.inspect({ signal: operationSignal, timeoutMs })), signal, false)
+        .catch(async (error: unknown) => {
+          this.lifetime.abort(error);
+          try { await this.protocol.close(); }
+          catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Pioneer startup and cleanup failed.'); }
+          throw error;
+        });
     }
-    if (!forceRefreshArg && this.configArg.snapshot) {
-      return false;
-    }
-    if (!forceRefreshArg && (this.configArg.rawData !== undefined || this.configArg.rawText !== undefined || this.configArg.entities?.length)) {
-      return false;
-    }
-    return true;
+    return this.startPromise;
   }
 
-  private async fetchSnapshot(): Promise<IPioneerSnapshot> {
-    const endpoint = this.requireEndpoint();
-    const connection = await PioneerTelnetConnection.connect(endpoint, this.configArg.timeoutMs || 3000);
-    try {
-      const commandTimeoutMs = this.configArg.commandTimeoutMs || 250;
-      const powerRaw = await connection.request('?P', 'PWR', commandTimeoutMs);
-      const volumeRaw = await connection.request('?V', 'VOL', commandTimeoutMs);
-      const muteRaw = await connection.request('?M', 'MUT', commandTimeoutMs);
-      const sourceNameToNumber = await this.sourceNameToNumber(connection, commandTimeoutMs);
-      const sourceNumberToName = reverseSourceMap(sourceNameToNumber);
-      const sourceRaw = await connection.request('?F', 'FN', commandTimeoutMs);
-      const sourceNumber = sourceRaw?.slice(2);
-      const source = sourceNumber ? sourceNumberToName[sourceNumber] || sourceNumber : undefined;
-      const volume = volumeRaw ? numberValue(volumeRaw.slice(3)) : undefined;
-      const state = pioneerPowerState(powerRaw);
-      const name = this.configArg.name || pioneerDefaultName;
-      const entity: ISimpleLocalEntitySnapshot = {
-        id: 'media_player',
-        uniqueId: `${pioneerProfile.domain}_${SimpleLocalMapper.slug(this.configArg.uniqueId || this.configArg.deviceId || endpoint.host)}_media_player`,
-        name,
-        platform: 'media_player',
-        state,
-        available: true,
-        writable: true,
-        attributes: cleanAttributes({
-          powerRaw,
-          volumeRaw,
-          volume,
-          volumeLevel: volume === undefined ? undefined : volume / pioneerMaxVolume,
-          isVolumeMuted: muteRaw === undefined ? undefined : muteRaw === 'MUT0',
-          muteRaw,
-          source,
-          sourceNumber,
-          sourceList: Object.keys(sourceNameToNumber).length ? Object.keys(sourceNameToNumber).sort() : undefined,
-          sources: Object.keys(sourceNameToNumber).length ? sourceNameToNumber : undefined,
-        }),
-      };
-
-      return {
-        device: {
-          id: this.configArg.uniqueId || this.configArg.deviceId || `${endpoint.host}:${endpoint.port}`,
-          name,
-          manufacturer: 'Pioneer',
-          model: stringValue(this.configArg.model) || 'Pioneer AVR',
-          serialNumber: this.configArg.macAddress,
-          host: endpoint.host,
-          port: endpoint.port,
-          protocol: 'telnet',
-        },
-        entities: [entity],
-        online: true,
-        updatedAt: new Date().toISOString(),
-        source: 'tcp',
-        rawData: {
-          powerRaw,
-          volumeRaw,
-          muteRaw,
-          sourceRaw,
-          sources: sourceNameToNumber,
-        },
-        capabilities: {
-          localRead: true,
-          localControl: true,
-          telnet: true,
-        },
-      };
-    } finally {
-      connection.close();
-    }
+  public getObservedSnapshot(): IPioneerSnapshot {
+    this.assertOpen();
+    if (!this.snapshot) throw new Error('Pioneer has no admitted observation.');
+    return this.snapshot;
   }
 
-  private async sourceNameToNumber(connectionArg: PioneerTelnetConnection, commandTimeoutMsArg: number): Promise<Record<string, string>> {
-    const configured = recordValue(this.configArg.sources) || recordValue(this.configArg.metadata?.sources);
-    if (configured) {
-      return configured;
-    }
-
-    const sources: Record<string, string> = {};
-    const limit = Math.max(0, Math.min(pioneerMaxSourceNumbers, this.configArg.sourceScanLimit ?? pioneerMaxSourceNumbers));
-    for (let index = 0; index < limit; index++) {
-      const response = await connectionArg.request(`?RGB${String(index).padStart(2, '0')}`, 'RGB', commandTimeoutMsArg);
-      const source = parseSourceResponse(response);
-      if (source) {
-        sources[source.name] = source.number;
-      }
-    }
-    return sources;
+  public getSnapshot(signal?: AbortSignal): Promise<IPioneerSnapshot> {
+    return this.run(async (operationSignal, timeoutMs) => this.observe(await this.protocol.inspect({ signal: operationSignal, timeoutMs })), signal);
   }
 
-  private async commandForService(requestArg: IServiceCallRequest): Promise<string> {
-    const data = requestArg.data || {};
-    if (typeof data.command === 'string' && data.command.trim()) {
-      return data.command.trim();
-    }
-    if (requestArg.service === 'turn_on') {
-      return 'PO';
-    }
-    if (requestArg.service === 'turn_off') {
-      return 'PF';
-    }
-    if (requestArg.service === 'volume_up') {
-      return 'VU';
-    }
-    if (requestArg.service === 'volume_down') {
-      return 'VD';
-    }
-    if (requestArg.service === 'volume_mute' || requestArg.service === 'mute_volume') {
-      return boolValue(data.mute ?? data.is_volume_muted ?? data.muted ?? true) ? 'MO' : 'MF';
-    }
-    if (requestArg.service === 'set_volume_level' || requestArg.service === 'volume_set' || requestArg.service === 'set_level') {
-      const requested = numberValue(data.volume_level ?? data.volume ?? data.level);
-      const percentage = numberValue(data.percentage);
-      const value = percentage !== undefined ? (percentage / 100) * pioneerMaxVolume : requested !== undefined && requested <= 1 ? requested * pioneerMaxVolume : requested;
-      if (value === undefined) {
-        throw new Error('Pioneer set_volume_level requires data.volume_level, data.volume, data.level, or data.percentage.');
-      }
-      return `${String(Math.max(0, Math.min(pioneerMaxVolume, Math.round(value)))).padStart(3, '0')}VL`;
-    }
-    if (requestArg.service === 'select_source') {
-      const sourceNumber = stringValue(data.sourceNumber) || stringValue(data.source_number) || stringValue(data.input);
-      if (sourceNumber && /^\d{2}$/.test(sourceNumber)) {
-        return `${sourceNumber}FN`;
-      }
-      const source = stringValue(data.source) || stringValue(data.source_name);
-      const sourceMap = recordValue(this.configArg.sources) || recordValue(this.configArg.metadata?.sources) || recordValue((await this.getSnapshot()).entities[0]?.attributes?.sources);
-      const mapped = source ? sourceMap?.[source] : undefined;
-      if (!mapped) {
-        throw new Error('Pioneer select_source requires data.sourceNumber or data.source matching configured/discovered sources.');
+  public async setControl(input: TPioneerControl, signal?: AbortSignal): Promise<IPioneerEffectResult> {
+    const control = validatePioneerControl(input);
+    if (control.feature === 'volume_raw' && control.value > this.config.maximumVolumeRaw) throw new TypeError('Pioneer volume exceeds the owner ceiling.');
+    return this.run(async (operationSignal, timeoutMs) => {
+      const options = { signal: operationSignal, timeoutMs };
+      const result = control.feature === 'power' ? await this.protocol.setPower(control.value, options)
+        : control.feature === 'muted' ? await this.protocol.setMuted(control.value, options)
+        : control.feature === 'volume_raw' ? await this.protocol.setVolumeRaw(control.value, options)
+        : await this.protocol.setInput(control.value, options);
+      try {
+        return Object.freeze({ dispatch: result.dispatch, outcome: result.outcome,
+          commandAcknowledged: result.commandAcknowledged, causalityConfirmed: result.causalityConfirmed,
+          snapshot: this.observe(result.observation) });
+      } catch {
+        throw new plugins.ecobridgeDeviceManager.PioneerProtocolError('identity-mismatch', 'Pioneer observation could not be admitted after dispatch.', 'indeterminate');
       }
-      return `${mapped}FN`;
-    }
-    throw new Error(`Unsupported Pioneer native service: ${requestArg.domain}.${requestArg.service}`);
+    }, signal);
   }
 
-  private requireEndpoint(): IPioneerEndpoint {
-    const endpoint = this.endpoint();
-    if (!endpoint) {
-      throw new Error('Pioneer Telnet requires config.host or config.url.');
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      // Publish the memo before protocol abort listeners can reenter this facade.
+      this.closePromise = Promise.resolve().then(() => this.drain());
+      this.lifetime.abort(new Error('Pioneer client is closed.'));
     }
-    return endpoint;
+    return this.closePromise;
   }
 
-  private endpoint(): IPioneerEndpoint | undefined {
-    const rawUrl = stringValue(this.configArg.url) || stringValue(this.configArg.metadata?.url);
-    if (rawUrl) {
-      const parsed = parseUrl(rawUrl);
-      if (parsed) {
-        return { host: parsed.hostname, port: this.configArg.port || numberValue(parsed.port) || pioneerDefaultPort };
-      }
-    }
-    const host = stringValue(this.configArg.host);
-    if (!host) {
-      return undefined;
+  /** Retries retained terminal cleanup only; never repeats protocol observations or effects. */
+  public retryCleanup(): Promise<void> {
+    const closed = this.closePromise;
+    if (!closed) return Promise.reject(new Error('Pioneer cleanup retry requires terminal destruction.'));
+    if (!this.retryPromise) {
+      const retry = Promise.resolve().then(async () => {
+        await closed.catch(() => undefined);
+        await this.drain();
+      });
+      this.retryPromise = retry;
+      const settled = (): void => { this.retryPromise = undefined; };
+      void retry.then(settled, settled);
     }
-    const parsedHost = parseUrl(host);
-    if (parsedHost) {
-      return { host: parsedHost.hostname, port: this.configArg.port || numberValue(parsedHost.port) || pioneerDefaultPort };
-    }
-    const hostPort = splitHostPort(host);
-    return { host: hostPort.host, port: this.configArg.port || hostPort.port || pioneerDefaultPort };
+    return this.retryPromise;
   }
 
-  private createOfflineSnapshot(errorArg: string): IPioneerSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: pioneerProfile, config: this.configArg, online: false, source: 'runtime', error: errorArg }) as IPioneerSnapshot;
+  private async drain(): Promise<void> {
+    const results = await Promise.allSettled([this.protocol.close(), this.operationTail, this.startPromise]);
+    this.snapshot = undefined;
+    const closure = results[0];
+    if (closure.status === 'rejected') throw closure.reason;
   }
-}
-
-interface IPioneerEndpoint {
-  host: string;
-  port: number;
-}
-
-class PioneerTelnetConnection {
-  private buffer = '';
-  private lines: string[] = [];
-  private waiters: Array<() => void> = [];
-  private closed = false;
-  private lastError?: Error;
 
-  private constructor(private readonly socket: plugins.net.Socket) {
-    socket.on('data', (chunkArg) => this.pushData(Buffer.isBuffer(chunkArg) ? chunkArg : Buffer.from(chunkArg)));
-    socket.on('close', () => {
-      this.closed = true;
-      this.notify();
-    });
-    socket.on('end', () => {
-      this.closed = true;
-      this.notify();
-    });
-    socket.on('error', (errorArg) => {
-      this.lastError = errorArg;
-      this.closed = true;
-      this.notify();
+  private observe(state: plugins.ecobridgeDeviceManager.IPioneerState): IPioneerSnapshot {
+    this.assertOpen();
+    this.snapshot = Object.freeze({
+      homeId: this.config.homeId, host: this.config.host, port: this.config.port,
+      name: this.config.name ?? state.identity.name, identity: Object.freeze({ ...state.identity }),
+      power: state.power, muted: state.muted, volumeRaw: state.volumeRaw, inputId: state.inputId,
+      observedInputs: Object.freeze([...this.protocol.observedInputs]), maximumVolumeRaw: this.config.maximumVolumeRaw,
+      observedAt: state.observedAt,
     });
+    return this.snapshot;
   }
 
-  public static async connect(endpointArg: IPioneerEndpoint, timeoutMsArg: number): Promise<PioneerTelnetConnection> {
-    return new Promise<PioneerTelnetConnection>((resolve, reject) => {
-      const socket = plugins.net.createConnection({ host: endpointArg.host, port: endpointArg.port });
-      let settled = false;
-      const finish = (connectionArg?: PioneerTelnetConnection, errorArg?: Error) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        socket.off('connect', onConnect);
-        socket.off('error', onError);
-        socket.off('timeout', onTimeout);
-        if (errorArg) {
-          socket.destroy();
-          reject(errorArg);
-          return;
-        }
-        resolve(connectionArg!);
-      };
-      const onConnect = () => finish(new PioneerTelnetConnection(socket));
-      const onError = (errorArg: Error) => finish(undefined, errorArg);
-      const onTimeout = () => finish(undefined, new Error(`Pioneer Telnet connection to ${endpointArg.host}:${endpointArg.port} timed out after ${timeoutMsArg}ms.`));
-      socket.setTimeout(timeoutMsArg);
-      socket.once('connect', onConnect);
-      socket.once('error', onError);
-      socket.once('timeout', onTimeout);
-    });
+  private assertOpen(): void {
+    this.lifetime.signal.throwIfAborted();
+    if (this.protocol.isClosed) throw new plugins.ecobridgeDeviceManager.PioneerProtocolError('closed', 'Pioneer protocol is terminally closed.');
+    this.admission.admit(this.context, this.config.homeId);
   }
 
-  public async request(commandArg: string, expectedPrefixArg: string, timeoutMsArg: number): Promise<string | undefined> {
-    await this.write(`${commandArg}\r`);
-    for (let index = 0; index < 3; index++) {
-      const line = await this.readLine(timeoutMsArg);
-      if (!line) {
-        return undefined;
-      }
-      if (line.startsWith(expectedPrefixArg)) {
-        return line;
-      }
-    }
-    return undefined;
+  private assertSignal(signal?: AbortSignal): void {
+    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('Pioneer cancellation requires an AbortSignal.');
+    signal?.throwIfAborted();
   }
 
-  public async write(dataArg: string): Promise<void> {
-    if (this.lastError) {
-      throw this.lastError;
-    }
-    await new Promise<void>((resolve, reject) => {
-      this.socket.write(dataArg, 'ascii', (errorArg) => errorArg ? reject(errorArg) : resolve());
+  /** Scope is checked when adapter work runs, before admission to the foundation's FIFO. */
+  private run<TResult>(execute: (signal: AbortSignal, timeoutMs: number) => Promise<TResult>, signal?: AbortSignal, started = true): Promise<TResult> {
+    try {
+      this.assertOpen(); this.assertSignal(signal);
+      if (started && !this.snapshot) throw new Error('Pioneer client has not started.');
+      if (this.pendingOperations >= this.config.maxPendingOperations) throw new Error('Pioneer operation capacity reached.');
+    } catch (error) { return Promise.reject(error); }
+    const deadline = performance.now() + this.config.timeoutMs;
+    const controller = new AbortController();
+    const combined = AbortSignal.any([this.lifetime.signal, controller.signal,
+      ...(this.context.abortSignal ? [this.context.abortSignal] : []), ...(signal ? [signal] : [])]);
+    const timer = setTimeout(() => controller.abort(new plugins.ecobridgeDeviceManager.PioneerProtocolError('timeout', 'Pioneer adapter deadline expired.')), this.config.timeoutMs);
+    this.pendingOperations++;
+    let rejectWaiting: () => void = () => {};
+    const waitingCancelled = new Promise<never>((_resolve, reject) => {
+      rejectWaiting = () => reject(combined.reason);
+      combined.addEventListener('abort', rejectWaiting, { once: true });
     });
-  }
-
-  public close(): void {
-    this.closed = true;
-    this.socket.destroy();
-    this.notify();
-  }
-
-  private async readLine(timeoutMsArg: number): Promise<string | undefined> {
-    if (this.lastError) {
-      throw this.lastError;
-    }
-    if (this.lines.length) {
-      return this.lines.shift();
-    }
-    if (this.closed) {
-      return undefined;
-    }
-    return new Promise<string | undefined>((resolve, reject) => {
-      let settled = false;
-      const cleanup = () => {
-        clearTimeout(timer);
-        this.waiters = this.waiters.filter((waiterArg) => waiterArg !== waiter);
-      };
-      const done = (valueArg?: string, errorArg?: Error) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        cleanup();
-        if (errorArg) {
-          reject(errorArg);
-          return;
-        }
-        resolve(valueArg);
-      };
-      const waiter = () => {
-        if (this.lastError) {
-          done(undefined, this.lastError);
-          return;
-        }
-        if (this.lines.length) {
-          done(this.lines.shift());
-          return;
-        }
-        if (this.closed) {
-          done(undefined);
-        }
-      };
-      const timer = setTimeout(() => done(undefined), timeoutMsArg);
-      this.waiters.push(waiter);
+    const operation = this.operationTail.then(async () => {
+      combined.removeEventListener('abort', rejectWaiting);
+      combined.throwIfAborted(); this.assertOpen();
+      const remaining = Math.floor(deadline - performance.now());
+      if (remaining < 1) throw new plugins.ecobridgeDeviceManager.PioneerProtocolError('timeout', 'Pioneer queued operation expired.');
+      return execute(combined, remaining);
+    }).finally(() => {
+      combined.removeEventListener('abort', rejectWaiting); clearTimeout(timer); this.pendingOperations--;
     });
-  }
-
-  private pushData(chunkArg: Buffer): void {
-    this.buffer += chunkArg.toString('ascii');
-    let match = /\r\n|\r|\n/.exec(this.buffer);
-    while (match?.index !== undefined) {
-      const line = this.buffer.slice(0, match.index).trim();
-      this.buffer = this.buffer.slice(match.index + match[0].length);
-      if (line) {
-        this.lines.push(line);
-      }
-      match = /\r\n|\r|\n/.exec(this.buffer);
-    }
-    this.notify();
-  }
-
-  private notify(): void {
-    const waiters = this.waiters.splice(0);
-    for (const waiter of waiters) {
-      waiter();
-    }
+    this.operationTail = operation.then(() => {}, () => {});
+    if (combined.aborted) rejectWaiting();
+    return Promise.race([operation, waitingCancelled]);
   }
 }
-
-const sendPioneerCommand = async (endpointArg: IPioneerEndpoint, commandArg: string, timeoutMsArg: number): Promise<void> => {
-  const connection = await PioneerTelnetConnection.connect(endpointArg, timeoutMsArg);
-  try {
-    await connection.write(`${commandArg}\r`);
-    await delay(40);
-  } finally {
-    connection.close();
-  }
-};
-
-const parseSourceResponse = (responseArg: string | undefined): { number: string; name: string } | undefined => {
-  const match = responseArg ? /^RGB(\d{2})\s*(.+)$/.exec(responseArg) : undefined;
-  const name = match?.[2]?.trim();
-  return match && name ? { number: match[1], name } : undefined;
-};
-
-const pioneerPowerState = (valueArg: string | undefined): string => {
-  if (valueArg === 'PWR0') {
-    return 'on';
-  }
-  if (valueArg === 'PWR1' || valueArg === 'PWR2') {
-    return 'off';
-  }
-  return 'unknown';
-};
-
-const reverseSourceMap = (sourcesArg: Record<string, string>): Record<string, string> => Object.fromEntries(Object.entries(sourcesArg).map(([nameArg, numberArg]) => [numberArg, nameArg]));
-
-const recordValue = (valueArg: unknown): Record<string, string> | undefined => {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
-    return undefined;
-  }
-  const entries = Object.entries(valueArg).filter((entryArg): entryArg is [string, string] => typeof entryArg[1] === 'string' && entryArg[1].trim().length > 0);
-  return entries.length ? Object.fromEntries(entries) : undefined;
-};
-
-const stringValue = (valueArg: unknown): string | undefined => typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-
-const numberValue = (valueArg: unknown): number | undefined => {
-  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-    return valueArg;
-  }
-  if (typeof valueArg === 'string' && valueArg.trim() && Number.isFinite(Number(valueArg))) {
-    return Number(valueArg);
-  }
-  return undefined;
-};
-
-const boolValue = (valueArg: unknown): boolean => valueArg === true || valueArg === 'true' || valueArg === '1' || valueArg === 1;
-
-const cleanAttributes = (attributesArg: Record<string, unknown>): Record<string, unknown> | undefined => {
-  const clean = Object.fromEntries(Object.entries(attributesArg).filter(([, valueArg]) => valueArg !== undefined));
-  return Object.keys(clean).length ? clean : undefined;
-};
-
-const parseUrl = (valueArg: string): URL | undefined => {
-  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(valueArg)) {
-    return undefined;
-  }
-  try {
-    return new URL(valueArg);
-  } catch {
-    return undefined;
-  }
-};
-
-const splitHostPort = (valueArg: string): { host: string; port?: number } => {
-  const match = /^([^:]+):(\d+)$/.exec(valueArg);
-  return match ? { host: match[1], port: Number(match[2]) } : { host: valueArg };
-};
-
-const delay = async (msArg: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, msArg));
-
-const errorMessage = (errorArg: unknown): string => errorArg instanceof Error ? errorArg.message : String(errorArg);