@tx5dr/plugin-api 1.7.12 → 2.5.0

package/dist/testing/index.js

@@ -39,21 +39,49 @@ function createMockHostDependencies() {
     };
 }
 // ===== Factory: KVStore =====
+function cloneJsonValue(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        return undefined;
+    return JSON.parse(serialized);
+}
+function cloneStructuredValue(value) {
+    if (Buffer.isBuffer(value))
+        return Buffer.from(value);
+    return structuredClone(value);
+}
 export function createMockKVStore(initial) {
-    const data = new Map(initial ? Object.entries(initial) : []);
+    const clonedInitial = initial ? cloneJsonValue(initial) : {};
+    const data = new Map(Object.entries(clonedInitial));
     return {
         _data: data,
         get(key, defaultValue) {
-            return (data.has(key) ? data.get(key) : defaultValue);
+            return (data.has(key) ? cloneJsonValue(data.get(key)) : defaultValue);
         },
         set(key, value) {
-            data.set(key, value);
+            const clonedEntry = cloneJsonValue({ [key]: value });
+            if (!Object.prototype.hasOwnProperty.call(clonedEntry, key)) {
+                data.delete(key);
+            }
+            else {
+                data.set(key, clonedEntry[key]);
+            }
+        },
+        update(key, reducer) {
+            const current = data.has(key) ? cloneJsonValue(data.get(key)) : undefined;
+            const next = reducer(current);
+            const clonedEntry = cloneJsonValue({ [key]: next });
+            if (!Object.prototype.hasOwnProperty.call(clonedEntry, key))
+                data.delete(key);
+            else
+                data.set(key, clonedEntry[key]);
+            return data.has(key) ? cloneJsonValue(data.get(key)) : undefined;
         },
         delete(key) {
             data.delete(key);
         },
         getAll() {
-            return Object.fromEntries(data);
+            return cloneJsonValue(Object.fromEntries(data));
         },
         async flush() {
             // no-op in mock
@@ -95,7 +123,7 @@ export function createMockTimers() {
         },
     };
 }
-// ===== Factory: OperatorControl =====
+// ===== Factory: Operator snapshot and commands =====
 const DEFAULT_MODE = {
     name: 'FT8',
     slotMs: 15000,
@@ -104,79 +132,125 @@ const DEFAULT_MODE = {
     transmitTiming: 1180,
     encodeAdvance: 400,
 };
-export function createMockOperatorControl(overrides) {
+export function createMockOperatorSnapshot(overrides) {
+    const mode = cloneStructuredValue(overrides?.mode ?? DEFAULT_MODE);
+    const transmitCycles = cloneStructuredValue(overrides?.transmitCycles ?? [0]);
+    const automation = cloneStructuredValue(overrides?.automation ?? null);
+    const getOtherOperators = overrides?.getOtherOperators ?? (() => []);
     return {
-        id: 'operator-0',
-        isTransmitting: false,
-        callsign: 'W1AW',
-        grid: 'FN31',
-        frequency: 1500,
-        mode: DEFAULT_MODE,
-        transmitCycles: [0],
-        automation: null,
-        getOtherOperators: () => [],
-        startTransmitting() { },
-        stopTransmitting() { },
-        call() { },
-        replyToDecode() { },
-        setTransmitCycles() { },
-        clearDecodes() { },
-        haltTransmission() { },
-        setFreeText() { },
-        sendFreeText() { },
-        setTemporaryLocation() { },
-        highlightCallsign() { },
-        hasWorkedCallsign: async () => false,
-        isTargetBeingWorkedByOthers: () => false,
-        recordQSO() { },
-        notifySlotsUpdated() { },
-        notifyStateChanged() { },
-        ...overrides,
+        id: overrides?.id ?? 'operator-0',
+        isTransmitting: overrides?.isTransmitting ?? false,
+        callsign: overrides?.callsign ?? 'W1AW',
+        grid: overrides?.grid ?? 'FN31',
+        frequency: overrides?.frequency ?? 1500,
+        maxConcurrentStreams: overrides?.maxConcurrentStreams ?? 3,
+        get mode() { return cloneStructuredValue(mode); },
+        get transmitCycles() { return cloneStructuredValue(transmitCycles); },
+        get automation() { return cloneStructuredValue(automation); },
+        getOtherOperators: () => cloneStructuredValue(getOtherOperators()),
+        hasWorkedCallsign: overrides?.hasWorkedCallsign ?? (async () => false),
+        isTargetBeingWorkedByOthers: overrides?.isTargetBeingWorkedByOthers ?? (() => false),
+    };
+}
+export function createMockOperatorCommandPort(submit) {
+    const commands = [];
+    return {
+        _commands: commands,
+        async submit(command) {
+            const snapshot = cloneStructuredValue(command);
+            commands.push(snapshot);
+            await submit?.(cloneStructuredValue(snapshot));
+            return { epoch: commands.length, outcome: 'completed' };
+        },
     };
 }
 // ===== Factory: RadioControl =====
-export function createMockRadioControl(overrides) {
-    const capabilitySnapshot = { descriptors: [], capabilities: [] };
-    const powerState = { state: 'awake', stage: 'idle' };
+export function createMockRadioView(overrides) {
+    const mode = cloneStructuredValue(overrides?.mode ?? {
+        engineMode: 'digital',
+        mode: 'FT8',
+        radioMode: 'USB',
+        descriptor: DEFAULT_MODE,
+    });
     return {
-        frequency: 14074000,
-        band: '20m',
-        mode: {
-            engineMode: 'digital',
-            mode: 'FT8',
-            radioMode: 'USB',
-            descriptor: DEFAULT_MODE,
-        },
-        isConnected: true,
-        capabilities: {
-            getSnapshot: () => capabilitySnapshot,
-            getState: (id) => capabilitySnapshot.capabilities.find((capability) => capability.id === id) ?? null,
-            refresh: async () => capabilitySnapshot,
-            write: async () => { },
-        },
-        power: {
-            getSupport: async (profileId = 'mock-profile') => ({
-                profileId,
-                canPowerOn: true,
-                canPowerOff: true,
-                supportedStates: ['off', 'standby', 'operate'],
-            }),
-            getState: () => powerState,
-            set: async (state) => ({ success: true, target: state, state: state === 'off' ? 'off' : 'awake' }),
-        },
-        setFrequency: async () => { },
-        ...overrides,
+        frequency: overrides?.frequency ?? 14074000,
+        band: overrides?.band ?? '20m',
+        get mode() { return cloneStructuredValue(mode); },
+        isConnected: overrides?.isConnected ?? true,
+        isSimulation: overrides?.isSimulation ?? false,
+    };
+}
+export function createMockRadioCapabilitiesView() {
+    const snapshot = { descriptors: [], capabilities: [] };
+    return {
+        getSnapshot: () => cloneStructuredValue(snapshot),
+        getState: (id) => cloneStructuredValue(snapshot.capabilities.find((capability) => capability.id === id) ?? null),
+        refresh: async () => cloneStructuredValue(snapshot),
+    };
+}
+export function createMockRadioCommandPort() {
+    return { submit: async () => { } };
+}
+export function createMockRadioTunerCommandPort() {
+    return { submit: async () => { } };
+}
+export function createMockRadioPowerView() {
+    const state = { state: 'awake', stage: 'idle' };
+    return {
+        getSupport: async (profileId = 'mock-profile') => ({
+            profileId,
+            canPowerOn: true,
+            canPowerOff: true,
+            supportedStates: ['off', 'standby', 'operate'],
+        }),
+        getState: () => cloneStructuredValue(state),
+    };
+}
+export function createMockRadioPowerCommandPort() {
+    return {
+        submit: async (command) => ({
+            success: true,
+            target: command.state,
+            state: command.state === 'off' ? 'off' : 'awake',
+        }),
     };
 }
 // ===== Factory: LogbookAccess =====
 export function createMockLogbookAccess(overrides) {
+    const commit = async (record) => cloneStructuredValue(record);
+    const update = async (qsoId, updates) => commit({
+        callsign: updates.callsign ?? 'N0CALL',
+        frequency: updates.frequency ?? 14_074_000,
+        mode: updates.mode ?? 'FT8',
+        startTime: updates.startTime ?? 0,
+        messageHistory: updates.messageHistory ?? [],
+        ...updates,
+        id: qsoId,
+    });
+    const readQsoSnapshot = async () => ({ revision: 'mock-revision', records: [] });
+    const applyQsoBatch = async (mutations) => ({
+        revision: 'mock-revision',
+        outcomes: await Promise.all(mutations.map(async (mutation, inputIndex) => {
+            if (mutation.type === 'add') {
+                return { inputIndex, status: 'added', record: await commit(mutation.record) };
+            }
+            return {
+                inputIndex,
+                status: 'updated',
+                record: await update(mutation.qsoId, mutation.updates),
+            };
+        })),
+    });
     const callsignAccess = {
         callsign: 'N0CALL',
         getLogBookId: async () => 'logbook-N0CALL',
+        awaitReady: async () => { },
         queryQSOs: async () => [],
+        readQsoSnapshot,
         countQSOs: async () => 0,
-        addQSO: async () => { },
-        updateQSO: async () => { },
+        addQSO: commit,
+        updateQSO: update,
+        applyQsoBatch,
         getStatistics: async () => null,
         notifyUpdated: async () => { },
     };
@@ -185,10 +259,12 @@ export function createMockLogbookAccess(overrides) {
         hasWorkedDXCC: async () => false,
         hasWorkedGrid: async () => false,
         queryQSOs: async () => [],
+        readQsoSnapshot,
         countQSOs: async () => 0,
         forCallsign: () => callsignAccess,
-        addQSO: async () => { },
-        updateQSO: async () => { },
+        addQSO: commit,
+        updateQSO: update,
+        applyQsoBatch,
         notifyUpdated: async () => { },
         ...overrides,
     };
@@ -206,33 +282,38 @@ export function createMockBandAccess(overrides) {
 // ===== Factory: UIBridge =====
 export function createMockUIBridge() {
     const sentData = new Map();
+    const events = [];
     return {
         _sentData: sentData,
+        _events: events,
         send(panelId, data) {
             const existing = sentData.get(panelId) ?? [];
-            existing.push(data);
+            existing.push(cloneJsonValue(data));
             sentData.set(panelId, existing);
         },
-        setPanelMeta(_panelId, _meta) {
-            // no-op in mock
+        setPanelMeta(panelId, meta) {
+            events.push({ type: 'panel-meta', id: panelId, data: cloneJsonValue(meta) });
         },
-        setPanelContributions(_groupId, _panels) {
-            // no-op in mock
+        setPanelContributions(groupId, panels) {
+            events.push({ type: 'panel-contributions', id: groupId, data: cloneJsonValue(panels) });
         },
-        clearPanelContributions(_groupId) {
-            // no-op in mock
+        clearPanelContributions(groupId) {
+            events.push({ type: 'panel-contributions', id: groupId, data: [] });
+        },
+        refreshOperatorProjection() {
+            events.push({ type: 'operator-projection-refresh', id: 'operator' });
         },
         registerPageHandler(_handler) {
             // no-op in mock
         },
-        pushToSession(_pageSessionId, _action, _data) {
-            // no-op in mock
+        pushToSession(pageSessionId, action, data) {
+            events.push({ type: 'session-push', id: `${pageSessionId}:${action}`, data: cloneJsonValue(data) });
         },
         listActivePageSessions(_pageId) {
             return [];
         },
-        pushToPage(_pageId, _action, _data) {
-            // no-op in mock
+        pushToPage(pageId, action, data) {
+            events.push({ type: 'page-push', id: `${pageId}:${action}`, data: cloneJsonValue(data) });
         },
     };
 }
@@ -240,8 +321,11 @@ export function createMockUIBridge() {
 export function createMockFileStore() {
     const storage = new Map();
     return {
-        async write(p, data) { storage.set(p, data); },
-        async read(p) { return storage.get(p) ?? null; },
+        async write(p, data) { storage.set(p, Buffer.from(data)); },
+        async read(p) {
+            const data = storage.get(p);
+            return data ? Buffer.from(data) : null;
+        },
         async delete(p) { return storage.delete(p); },
         async list(prefix) {
             const keys = Array.from(storage.keys());
@@ -268,7 +352,9 @@ export function createMockNetworkControl() {
                     async _emitMessage(data, remote) {
                         if (!messageHandler)
                             return;
-                        const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+                        const payload = typeof data === 'string'
+                            ? Buffer.from(data, 'utf8')
+                            : new Uint8Array(data);
                         await messageHandler(payload, {
                             address: remote?.address ?? '127.0.0.1',
                             port: remote?.port ?? 2237,
@@ -283,7 +369,11 @@ export function createMockNetworkControl() {
                         binds.push(options);
                     },
                     async send(data, port, host) {
-                        sent.push({ data, port, host });
+                        sent.push({
+                            data: typeof data === 'string' ? data : new Uint8Array(data),
+                            port,
+                            host,
+                        });
                     },
                     onMessage(handler) {
                         messageHandler = handler;
@@ -304,6 +394,77 @@ export function createMockNetworkControl() {
         },
     };
 }
+/**
+ * Creates a mock {@link PluginEventBus} for unit testing plugin code.
+ *
+ * All published messages are recorded in `_published` for assertion.
+ * The internal `_subscriptions` map lets tests inspect active subscriptions.
+ *
+ * @param options - Optional configuration for publisher metadata.
+ * @returns A mock event bus with inspection helpers.
+ *
+ * @example
+ * ```ts
+ * const bus = createMockEventBus({ owner: { pluginName: 'my-plugin' } });
+ * bus.subscribe('topic', handler);
+ * bus.publish('topic', { value: 42 });
+ * expect(bus._published).toHaveLength(1);
+ * expect(bus._published[0].publisher.pluginName).toBe('my-plugin');
+ * ```
+ */
+export function createMockEventBus(options) {
+    const subscriptions = new Map();
+    const published = [];
+    const ownerName = options?.owner?.pluginName ?? 'mock-plugin';
+    const ownerScope = options?.owner?.instanceScope ?? 'operator';
+    const ownerId = ownerScope === 'operator'
+        ? (options?.owner?.operatorId ?? 'operator-0')
+        : undefined;
+    return {
+        _subscriptions: subscriptions,
+        _published: published,
+        publish(topic, payload) {
+            const message = cloneStructuredValue({
+                topic,
+                payload: cloneStructuredValue(payload),
+                timestamp: Date.now(),
+                publisher: {
+                    pluginName: ownerName,
+                    instanceScope: ownerScope,
+                    operatorId: ownerId,
+                },
+            });
+            published.push(cloneStructuredValue(message));
+            const handlers = [...(subscriptions.get(topic) ?? [])];
+            for (const handler of handlers) {
+                try {
+                    void Promise.resolve(handler(cloneStructuredValue(message))).catch(() => undefined);
+                }
+                catch {
+                    // Match the production bus: subscriber failures do not reach publishers.
+                }
+            }
+        },
+        subscribe(topic, handler) {
+            const handlers = subscriptions.get(topic) ?? [];
+            if (!handlers.includes(handler)) {
+                handlers.push(handler);
+                subscriptions.set(topic, handlers);
+            }
+            return () => {
+                const current = subscriptions.get(topic);
+                if (!current)
+                    return;
+                const next = current.filter((candidate) => candidate !== handler);
+                if (next.length === 0) {
+                    subscriptions.delete(topic);
+                    return;
+                }
+                subscriptions.set(topic, next);
+            };
+        },
+    };
+}
 // ===== Factory: HostSettingsControl =====
 export function createMockHostSettingsControl(overrides) {
     const ft8 = {
@@ -337,33 +498,58 @@ export function createMockHostSettingsControl(overrides) {
     const ntp = { servers: ['pool.ntp.org'], defaultServers: ['pool.ntp.org'] };
     return {
         ft8: {
-            async get() { return ft8; },
-            async update(patch) { Object.assign(ft8, patch); return ft8; },
+            async get() { return cloneStructuredValue(ft8); },
+            async update(patch) {
+                Object.assign(ft8, cloneStructuredValue(patch));
+                return cloneStructuredValue(ft8);
+            },
         },
         decodeWindows: {
-            async get() { return decodeWindows; },
-            async update(settings) { Object.assign(decodeWindows, settings); return decodeWindows; },
+            async get() { return cloneStructuredValue(decodeWindows); },
+            async update(settings) {
+                Object.assign(decodeWindows, cloneStructuredValue(settings));
+                return cloneStructuredValue(decodeWindows);
+            },
         },
         realtime: {
-            async get() { return realtime; },
-            async update(settings) { Object.assign(realtime, settings); return realtime; },
+            async get() { return cloneStructuredValue(realtime); },
+            async update(settings) {
+                Object.assign(realtime, cloneStructuredValue(settings));
+                return cloneStructuredValue(realtime);
+            },
         },
         frequencyPresets: {
-            async get() { return frequencyPresets; },
-            async update(presets) { frequencyPresets.presets = presets; frequencyPresets.isCustomized = true; return frequencyPresets; },
-            async reset() { frequencyPresets.isCustomized = false; return frequencyPresets; },
+            async get() { return cloneStructuredValue(frequencyPresets); },
+            async update(presets) {
+                frequencyPresets.presets = cloneStructuredValue(presets);
+                frequencyPresets.isCustomized = true;
+                return cloneStructuredValue(frequencyPresets);
+            },
+            async reset() {
+                frequencyPresets.isCustomized = false;
+                return cloneStructuredValue(frequencyPresets);
+            },
         },
         station: {
-            async get() { return station; },
-            async update(patch) { Object.assign(station, patch); return station; },
+            async get() { return cloneStructuredValue(station); },
+            async update(patch) {
+                Object.assign(station, cloneStructuredValue(patch));
+                return cloneStructuredValue(station);
+            },
         },
         pskReporter: {
-            async get() { return pskReporter; },
-            async update(patch) { Object.assign(pskReporter, patch); return pskReporter; },
+            async get() { return cloneStructuredValue(pskReporter); },
+            async update(patch) {
+                Object.assign(pskReporter, cloneStructuredValue(patch));
+                return cloneStructuredValue(pskReporter);
+            },
         },
         ntp: {
-            async get() { return ntp; },
-            async update(request) { ntp.servers = request.servers; return ntp; },
+            async get() { return cloneStructuredValue(ntp); },
+            async update(request) {
+                ntp.servers = cloneStructuredValue(request.servers);
+                return cloneStructuredValue(ntp);
+            },
         },
         ...overrides,
     };
@@ -378,7 +564,7 @@ export function createMockContext(options) {
     const mode = opts.mode
         ? { ...DEFAULT_MODE, ...opts.mode }
         : DEFAULT_MODE;
-    const operator = createMockOperatorControl({
+    const operator = createMockOperatorSnapshot({
         id: opts.operatorId ?? 'operator-0',
         callsign: opts.callsign ?? 'W1AW',
         grid: opts.grid ?? 'FN31',
@@ -386,33 +572,114 @@ export function createMockContext(options) {
         mode,
         ...opts.operator,
     });
-    const radio = createMockRadioControl(opts.radio);
+    const radio = createMockRadioView(opts.radio);
     const logbook = createMockLogbookAccess(opts.logbook);
+    const logbookSessions = opts.logbookSessions ?? {
+        async open(descriptor) {
+            const access = logbook.forCallsign(descriptor.stationCallsign);
+            return {
+                ...access,
+                id: `plugin-session-${descriptor.sessionKey}`,
+                title: descriptor.title,
+                async destroy() { },
+            };
+        },
+        async destroy() { },
+    };
+    const readOnlyLogbook = {
+        hasWorked: logbook.hasWorked,
+        hasWorkedDXCC: logbook.hasWorkedDXCC,
+        hasWorkedGrid: logbook.hasWorkedGrid,
+        queryQSOs: logbook.queryQSOs,
+        readQsoSnapshot: logbook.readQsoSnapshot,
+        countQSOs: logbook.countQSOs,
+        forCallsign(callsign) {
+            const access = logbook.forCallsign(callsign);
+            return {
+                callsign: access.callsign,
+                getLogBookId: access.getLogBookId,
+                awaitReady: access.awaitReady,
+                queryQSOs: access.queryQSOs,
+                readQsoSnapshot: access.readQsoSnapshot,
+                countQSOs: access.countQSOs,
+                getStatistics: access.getStatistics,
+            };
+        },
+    };
     const band = createMockBandAccess(opts.band);
     const settings = createMockHostSettingsControl(opts.settings);
     const files = createMockFileStore();
     const network = opts.network ?? createMockNetworkControl();
+    const eventBus = opts.eventBus ?? createMockEventBus();
     const hostDependencies = opts.hostDependencies
         ?? (opts.permissions?.includes('host:hamlib') ? createMockHostDependencies() : {});
     const logbookSync = { register() { } };
+    const configState = cloneJsonValue(opts.config ?? {});
     return {
-        config: opts.config ?? {},
+        pluginApiVersion: opts.pluginApiVersion ?? '2.5.0',
+        get config() {
+            return cloneStructuredValue(configState);
+        },
         async updateConfig(patch) {
-            // no-op in mock
+            Object.assign(configState, cloneJsonValue(patch));
         },
         store: { global: globalStore, operator: operatorStore },
+        digitalMessagePreflight: {
+            async check(request) {
+                const text = request.text.trim().toUpperCase().replace(/\s+/g, ' ');
+                return text
+                    ? { encodable: true, requestedText: text, transmittedText: text }
+                    : { encodable: false, requestedText: text, reason: 'empty' };
+            },
+        },
         log,
         timers,
         operator,
         radio,
-        logbook,
         band,
         ui,
-        settings,
-        hostDependencies,
         files,
-        network,
-        logbookSync,
+        ...((opts.permissions?.includes('logbook:read')
+            || opts.permissions?.includes('logbook:write')
+            || opts.permissions?.includes('logbook:session')) ? {
+            logbook: {
+                ...(opts.permissions?.includes('logbook:write')
+                    ? logbook
+                    : opts.permissions?.includes('logbook:read') ? readOnlyLogbook : {}),
+                ...(opts.permissions?.includes('logbook:session') ? { sessions: logbookSessions } : {}),
+            },
+        } : {}),
+        ...(opts.permissions?.includes('logbook:sync') ? { logbookSync } : {}),
+        ...((opts.permissions ?? []).some(permission => permission.startsWith('settings:')) ? {
+            settings: {
+                ...(opts.permissions?.includes('settings:ft8') ? { ft8: settings.ft8 } : {}),
+                ...(opts.permissions?.includes('settings:decode-windows') ? { decodeWindows: settings.decodeWindows } : {}),
+                ...(opts.permissions?.includes('settings:realtime') ? { realtime: settings.realtime } : {}),
+                ...(opts.permissions?.includes('settings:frequency-presets') ? { frequencyPresets: settings.frequencyPresets } : {}),
+                ...(opts.permissions?.includes('settings:station') ? { station: settings.station } : {}),
+                ...(opts.permissions?.includes('settings:psk-reporter') ? { pskReporter: settings.pskReporter } : {}),
+                ...(opts.permissions?.includes('settings:ntp') ? { ntp: settings.ntp } : {}),
+            },
+        } : {}),
+        ...(opts.permissions?.includes('operator:transmit-control') ? {
+            operatorCommands: opts.operatorCommands ?? createMockOperatorCommandPort(),
+        } : {}),
+        ...(opts.permissions?.includes('radio:read') ? {
+            radioCapabilities: opts.radioCapabilities ?? createMockRadioCapabilitiesView(),
+            radioPower: opts.radioPower ?? createMockRadioPowerView(),
+        } : {}),
+        ...(opts.permissions?.includes('radio:control') ? {
+            radioCommands: opts.radioCommands ?? createMockRadioCommandPort(),
+        } : {}),
+        ...(opts.permissions?.includes('radio:tuner-control') ? {
+            radioTunerCommands: opts.radioTunerCommands ?? createMockRadioTunerCommandPort(),
+        } : {}),
+        ...(opts.permissions?.includes('radio:power') ? {
+            radioPowerCommands: opts.radioPowerCommands ?? createMockRadioPowerCommandPort(),
+        } : {}),
+        ...(opts.permissions?.includes('host:hamlib') ? { hostDependencies } : {}),
+        ...(opts.permissions?.includes('network') ? { network, fetch: globalThis.fetch } : {}),
+        ...(opts.permissions?.includes('plugin:event-bus') ? { eventBus } : {}),
     };
 }
 // ===== Data factories =====