@tx5dr/plugin-api 1.7.12 → 2.0.0

package/README.md

@@ -15,12 +15,14 @@ npm install --save-dev @tx5dr/plugin-api
 ### TypeScript
 
 ```typescript
-import type { PluginDefinition, PluginContext } from '@tx5dr/plugin-api';
+import { definePlugin } from '@tx5dr/plugin-api';
 
-const plugin: PluginDefinition = {
+const plugin = definePlugin({
+  apiVersion: 2,
   name: 'my-plugin',
   version: '1.0.0',
   type: 'utility',
+  permissions: [],
   hooks: {
     onDecode(messages, ctx) {
       for (const msg of messages) {
@@ -28,7 +30,7 @@ const plugin: PluginDefinition = {
       }
     },
   },
-};
+});
 
 export default plugin;
 ```
@@ -36,11 +38,14 @@ export default plugin;
 ### JavaScript (with JSDoc types)
 
 ```javascript
-/** @type {import('@tx5dr/plugin-api').PluginDefinition} */
-export default {
+import { definePlugin } from '@tx5dr/plugin-api';
+
+export default definePlugin({
+  apiVersion: 2,
   name: 'my-plugin',
   version: '1.0.0',
   type: 'utility',
+  permissions: [],
   hooks: {
     onDecode(messages, ctx) {
       for (const msg of messages) {
@@ -48,32 +53,118 @@ export default {
       }
     },
   },
-};
+});
 ```
 
 ## Exports
 
 | Subpath | Description |
 |---------|-------------|
-| `@tx5dr/plugin-api` | Core types: `PluginDefinition`, `PluginContext`, `PluginHooks`, helper interfaces, radio/message types |
-| `@tx5dr/plugin-api/testing` | Mock factories for unit testing: `createMockContext()`, `createMockSlotInfo()`, `createMockParsedMessage()` |
+| `@tx5dr/plugin-api` | `definePlugin()`, capability-derived contexts, hooks, structured command ports, and radio/message types |
+| `@tx5dr/plugin-api/testing` | Mock factories for unit testing: `createMockContext()`, `createMockSlotInfo()`, `createMockParsedMessage()`, `createMockEventBus()` |
 | `@tx5dr/plugin-api/bridge` | Ambient type declarations for the iframe Bridge SDK (`window.tx5dr`) |
 
+## Capability Model
+
+Privileged Host APIs use an allowlist model. A plugin must declare every
+capability in `permissions`; the Host then projects only those properties into
+that plugin's context. Undeclared properties are absent from both the inferred
+TypeScript type and the runtime object. Use `definePlugin()` without manually
+widening callbacks to `PluginContext`, otherwise TypeScript cannot preserve the
+literal permission tuple.
+
+Capabilities grant structured Host ports, not physical device ownership. The
+capability-derived context does not directly expose raw PTT, audio playback,
+the mixer, encoder, physical frame lease, arbitrary radio capability writes,
+or global emergency stop. Strategy runtimes receive a narrower speculative
+context and return declarative decisions; they never receive command ports.
+
+For a strategy plugin, `type: 'strategy'` plus `apiVersion: 2` is the explicit
+declaration that it may produce RF decisions when selected by an operator. It
+does not need `operator:transmit-control`. That permission is reserved for
+utility plugins that need the imperative, Host-coordinated
+`ctx.operatorCommands` port.
+
+API v2 is required for strategy plugins and any plugin requesting a mutation
+capability. The Host validates and freezes the loaded definition so permissions
+cannot be expanded after load.
+
+This is a Host API contract, not a sandbox for hostile Node.js code. Third-party
+plugins currently execute in the server process; process isolation is a
+separate security boundary.
+
+## Data Ownership and Callback Lifetime
+
+Configuration, hook arguments, query results and messages cross the Host boundary by value. Plugins may modify their local copies, but changes are not persisted until they call an explicit API such as `ctx.updateConfig()`, `store.set()` or a command port. UI/config/KV channels accept JSON-compatible values; hooks, strategy results and EventBus payloads accept structured-clone-compatible values. Functions, cycles, Host handles and other unsupported values are rejected with `PLUGIN_DATA_NOT_SERIALIZABLE`.
+
+Host capabilities such as `ctx.ui`, `ctx.logbook`, radio command ports, network sockets and native `Response` objects are live handles. Use them only before the current Host callback settles. A handle retained past timeout, reload or unload rejects with `PLUGIN_INVOCATION_EXPIRED`; use Host timers and callbacks for later work instead of detached continuations.
+
+## Operator Transmit Control
+
+Utility plugins that need to submit operator commands must declare
+`operator:transmit-control` and submit one of the high-level commands accepted
+by `ctx.operatorCommands`. The permission grants API access; it does not by
+itself classify the plugin as an automatic caller.
+
+Automatic calling plugins implement `isAutoCallEnabled()`. This both gates the
+command port and opts the plugin into the operator auto-call indicator and pause
+controls:
+
+```ts
+const plugin = definePlugin({
+  apiVersion: 2,
+  name: 'scheduled-caller',
+  version: '1.0.0',
+  type: 'utility',
+  permissions: ['operator:transmit-control'],
+  isAutoCallEnabled: (ctx) => ctx.config.enabled === true,
+  hooks: {
+    async onTimer(_timerId, ctx) {
+      await ctx.operatorCommands.submit({
+        type: 'request-call',
+        callsign: 'W1AW',
+      });
+    },
+  },
+});
+```
+
+Integrations such as remote-control protocol bridges that may submit occasional
+commands but do not autonomously originate calls implement
+`isTransmitControlEnabled()` instead. They receive the same guarded command
+port but are not shown or paused as auto-call plugins.
+
+The Host allocates an operator command epoch and routes the request through the
+operator/frame coordinators. Plugins cannot directly key or unkey the radio.
+
 ## Radio Permissions
 
-Server-side plugins can use `ctx.radio` to inspect negotiated radio capabilities and, when explicitly permitted, control radio capabilities or physical power:
+`ctx.radio` always exposes a small read-only operating snapshot. Additional
+radio capabilities require explicit declarations:
 
 ```ts
-permissions: ['radio:read', 'radio:control', 'radio:power']
+permissions: ['radio:read', 'radio:control', 'radio:tuner-control', 'radio:power']
 ```
 
-- `radio:read` enables `ctx.radio.capabilities.getSnapshot()` and `ctx.radio.power.getSupport()`.
-- `radio:control` enables `ctx.radio.setFrequency()` and `ctx.radio.capabilities.write()`.
-- `radio:power` enables `ctx.radio.power.set('on' | 'off' | 'standby' | 'operate')`.
-- `ctx.radio.mode` is always readable and exposes the current best-known operating mode using ADIF `MODE`/`SUBMODE` semantics, for example `SSB` + `USB` in voice USB.
+- `radio:read` exposes `ctx.radioCapabilities` and the read-only `ctx.radioPower` view.
+- `radio:control` exposes Host-arbitrated `set-frequency` and `switch-band` commands.
+- `switch-band` can include `autoTune: true` when `radio:tuner-control` is also declared; the Host keeps the complete operation inside one physical-idle fence.
+- `radio:tuner-control` exposes only `set-enabled` and `start-manual-tune` through `ctx.radioTunerCommands`.
+- Radio writes reject while Digital, Voice, CW, Tune or manual PTT owns the physical transmitter; they never interrupt that transmission.
+- `radio:power` exposes `ctx.radioPowerCommands.submit({ type: 'set-power', state })`.
+- `ctx.radio.mode` remains read-only and uses ADIF `MODE`/`SUBMODE` semantics.
 
 These APIs are not exposed directly to iframe pages; custom UI should call a server-side page handler.
 
+## Logbook Permissions
+
+- `logbook:read` exposes only query and worked-status methods on `ctx.logbook`.
+- `logbook:write` exposes durable `addQSO()`/`updateQSO()` mutations in addition to reads.
+- `logbook:sync` exposes `ctx.logbookSync` for registering a Host-managed sync provider.
+
+Write completion means the Host logbook durability contract has completed.
+Logbook APIs never grant PTT or frame lifecycle control.
+
 ## Host Settings Permissions
 
 Server-side plugins can use `ctx.settings` to read or update a safe whitelist of host settings when the manifest declares the matching permission. Each settings namespace uses one read/write permission:
@@ -89,9 +180,10 @@ Server-side plugins can use `ctx.settings` to read or update a safe whitelist of
 | `ctx.settings.ntp` | `settings:ntp` | `get()`, `update({ servers })` |
 
 ```ts
-import type { PluginDefinition } from '@tx5dr/plugin-api';
+import { definePlugin } from '@tx5dr/plugin-api';
 
-const plugin: PluginDefinition = {
+const plugin = definePlugin({
+  apiVersion: 2,
   name: 'station-policy',
   version: '1.0.0',
   type: 'utility',
@@ -102,13 +194,178 @@ const plugin: PluginDefinition = {
       await ctx.settings.station.update({ callsign: 'W1AW' });
     },
   },
-};
+});
 
 export default plugin;
 ```
 
 The whitelist intentionally excludes authentication tokens, operator CRUD, hardware radio connection settings, audio devices, rigctld, OpenWebRX, profiles, and server host/port settings. These APIs are not exposed directly to iframe pages; custom UI should call a server-side page handler with `window.tx5dr.invoke()`.
 
+## Plugin Event Bus
+
+Server-side plugins can exchange in-process messages through `ctx.eventBus`, a topic-based pub/sub bus scoped to the host process. Payloads use structured-clone semantics and each subscriber receives an independent value, enabling loose coupling without shared mutable state. Functions, promises, weak collections, and host capability objects cannot be published.
+
+### Permission
+
+Declare `plugin:event-bus` in the manifest to enable the bus:
+
+```ts
+permissions: ['plugin:event-bus']
+```
+
+`ctx.eventBus` is optional and should be feature-detected before use.
+
+### API Summary
+
+| Method | Description |
+|--------|-------------|
+| `publish(topic, payload?)` | Fire-and-forget message to all current subscribers of the exact topic. |
+| `subscribe(topic, handler)` | Registers a handler; returns an unsubscribe function. |
+
+Every message received by a subscriber is a `PluginEventBusMessage`:
+
+```ts
+interface PluginEventBusMessage {
+  topic: string;           // The topic this message was published to
+  payload: unknown;        // Independent structured-clone value
+  timestamp: number;       // Epoch ms when the host dispatched the message
+  publisher: {
+    pluginName: string;    // Publishing plugin's name
+    instanceScope: 'operator' | 'global';
+    operatorId?: string;   // Present when the publisher is operator-scoped
+  };
+}
+```
+
+### Topic Naming Convention
+
+Use dot-separated, plugin-prefixed names to avoid collisions between plugins:
+
+```
+<plugin-name>.<domain>.<event>
+```
+
+Examples:
+- `psk-reporter.spot.sent` — a spot was uploaded to PSK Reporter
+- `callsign-filter.match.found` — a callsign matched a filter rule
+- `logbook-sync.upload.complete` — a logbook sync finished
+
+Avoid generic names like `update` or `message` — they will collide.
+
+### Basic Usage
+
+```ts
+import { definePlugin } from '@tx5dr/plugin-api';
+
+// Publisher plugin
+const publisher = definePlugin({
+  apiVersion: 2,
+  name: 'spot-monitor',
+  version: '1.0.0',
+  type: 'utility',
+  permissions: ['plugin:event-bus'],
+  hooks: {
+    onDecode(messages, ctx) {
+      for (const msg of messages) {
+        ctx.eventBus.publish('spot-monitor.new-spot', {
+          callsign: msg.callsign,
+          frequency: msg.frequencyHz,
+        });
+      }
+    },
+  },
+});
+
+// Subscriber plugin
+const subscriber = definePlugin({
+  apiVersion: 2,
+  name: 'spot-logger',
+  version: '1.0.0',
+  type: 'utility',
+  permissions: ['plugin:event-bus'],
+  hooks: {
+    onLoad(ctx) {
+      ctx.eventBus.subscribe('spot-monitor.new-spot', (message) => {
+        ctx.log.info('received spot', {
+          from: message.publisher.pluginName,
+          callsign: (message.payload as any).callsign,
+        });
+      });
+    },
+  },
+});
+```
+
+### Cross-Operator Communication
+
+Operator-scoped plugins can communicate across operators on the same host. The `publisher` metadata lets subscribers identify which operator sent the message:
+
+```ts
+ctx.eventBus.subscribe('qso-monitor.qso-complete', (message) => {
+  const { callsign, band } = message.payload as any;
+  ctx.log.info('QSO completed by another operator', {
+    operator: message.publisher.operatorId,
+    callsign,
+    band,
+  });
+});
+```
+
+### Lifecycle and Error Handling
+
+- **Auto-cleanup**: the host removes all subscriptions when a plugin instance unloads. No manual cleanup required.
+- **Manual unsubscribe**: call the function returned by `subscribe()` to cancel a single subscription early.
+- **Error isolation**: subscriber exceptions (sync or async) are captured and logged by the host. They never propagate back to the publisher.
+- **Delivery order**: subscribers receive messages in registration order. Async handlers are awaited, but the publisher does not wait for completion.
+
+### Testing
+
+Use `createMockEventBus()` from `@tx5dr/plugin-api/testing` to test plugin event bus logic in isolation:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { createMockEventBus } from '@tx5dr/plugin-api/testing';
+
+it('publishes spot data', () => {
+  const bus = createMockEventBus({ owner: { pluginName: 'spot-monitor' } });
+  const handler = vi.fn();
+
+  bus.subscribe('spot-monitor.new-spot', handler);
+  bus.publish('spot-monitor.new-spot', { callsign: 'W1AW', frequency: 14074000 });
+
+  expect(handler).toHaveBeenCalledTimes(1);
+  expect(handler).toHaveBeenCalledWith(expect.objectContaining({
+    topic: 'spot-monitor.new-spot',
+    payload: { callsign: 'W1AW', frequency: 14074000 },
+    publisher: expect.objectContaining({ pluginName: 'spot-monitor' }),
+  }));
+});
+
+it('tracks published messages', () => {
+  const bus = createMockEventBus();
+
+  bus.publish('topic-a', { value: 1 });
+  bus.publish('topic-b', { value: 2 });
+
+  expect(bus._published).toHaveLength(2);
+  expect(bus._published[0].topic).toBe('topic-a');
+});
+
+it('unsubscribe prevents further delivery', () => {
+  const bus = createMockEventBus();
+  const handler = vi.fn();
+
+  const unsub = bus.subscribe('topic', handler);
+  bus.publish('topic', 'first');
+  unsub();
+  bus.publish('topic', 'second');
+
+  expect(handler).toHaveBeenCalledTimes(1);
+});
+```
+
+The mock records all published messages in `_published` and exposes the internal `_subscriptions` map for advanced inspection.
+
 ## Bridge SDK Types
 
 Plugin iframe pages communicate with the host via the Bridge SDK (`window.tx5dr`), which is automatically injected by the host. To get IDE autocomplete for the Bridge SDK, add the type reference to your project:

package/dist/__tests__/adif.test.js

@@ -29,4 +29,44 @@ describe('ADIF QSO mode projection', () => {
         expect(parsed?.submode).toBe('USB');
     });
 });
+describe('ADIF QSO comments', () => {
+    it('exports WSJT-X compatible signal reports in COMMENT', () => {
+        const adif = convertQSOToADIF(createQso({
+            mode: 'FT8',
+            submode: undefined,
+            reportSent: '-12',
+            reportReceived: '-09',
+        }));
+        expect(adif).toMatch(/<comment:\d+>FT8 {2}Sent: -12 {2}Rcvd: -09/);
+    });
+    it('keeps operator comments after the signal report COMMENT prefix', () => {
+        const adif = convertQSOToADIF(createQso({
+            mode: 'FT8',
+            submode: undefined,
+            reportSent: '-12',
+            reportReceived: '-09',
+            comment: 'TU',
+        }));
+        expect(adif).toMatch(/<comment:\d+>FT8 {2}Sent: -12 {2}Rcvd: -09 \| TU/);
+    });
+    it('stores message history in a TX-5DR private field instead of COMMENT', () => {
+        const adif = convertQSOToADIF(createQso({
+            mode: 'FT8',
+            submode: undefined,
+            reportSent: undefined,
+            reportReceived: undefined,
+            messageHistory: ['CQ TEST', 'RR73'],
+        }));
+        expect(adif).toMatch(/<app_tx5dr_message_history:\d+>CQ TEST \| RR73/);
+        expect(adif).not.toMatch(/<comment:\d+>CQ TEST/);
+    });
+    it('parses private message history and legacy COMMENT history', () => {
+        const parsedPrivate = parseADIFRecord('<call:6>N0CALL<qso_date:8>20260417<time_on:6>120000<mode:3>FT8<freq:9>14.074000<comment:25>FT8  Sent: -12  Rcvd: -09<app_tx5dr_message_history:14>CQ TEST | RR73<eor>', 'test');
+        const parsedLegacy = parseADIFRecord('<call:6>N0CALL<qso_date:8>20260417<time_on:6>120000<mode:3>FT8<freq:9>14.074000<comment:14>CQ TEST | RR73<eor>', 'test');
+        expect(parsedPrivate?.comment).toBe('FT8  Sent: -12  Rcvd: -09');
+        expect(parsedPrivate?.messageHistory).toEqual(['CQ TEST', 'RR73']);
+        expect(parsedLegacy?.comment).toBe('CQ TEST | RR73');
+        expect(parsedLegacy?.messageHistory).toEqual(['CQ TEST', 'RR73']);
+    });
+});
 //# sourceMappingURL=adif.test.js.map

package/dist/__tests__/adif.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"adif.test.js","sourceRoot":"","sources":["../../src/__tests__/adif.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGrE,SAAS,SAAS,CAAC,YAAgC,EAAE;IACnD,OAAO;QACL,EAAE,EAAE,WAAW;QACf,QAAQ,EAAE,QAAQ;QAClB,SAAS,EAAE,UAAU;QACrB,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC;QACjD,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC;QAC/C,UAAU,EAAE,IAAI;QAChB,cAAc,EAAE,IAAI;QACpB,cAAc,EAAE,EAAE;QAClB,UAAU,EAAE,QAAQ;QACpB,MAAM,EAAE,QAAQ;QAChB,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,IAAI,GAAG,gBAAgB,CAAC,SAAS,EAAE,CAAC,CAAC;QAE3C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,MAAM,GAAG,eAAe,CAC5B,sFAAsF,EACtF,MAAM,CACP,CAAC;QAEF,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"adif.test.js","sourceRoot":"","sources":["../../src/__tests__/adif.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/capability-context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capability-context.test.d.ts.map

package/dist/__tests__/capability-context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-context.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/capability-context.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/capability-context.test.js

@@ -0,0 +1,99 @@
+import { describe, it } from 'vitest';
+import { definePlugin } from '../definition.js';
+describe('capability-derived plugin contexts', () => {
+    it('keeps speculative strategy factories free of command capabilities', () => {
+        definePlugin({
+            apiVersion: 2,
+            name: 'safe-strategy',
+            version: '1.0.0',
+            type: 'strategy',
+            permissions: ['operator:transmit-control', 'radio:control'],
+            createStrategyRuntime(ctx) {
+                // @ts-expect-error strategy factories receive only the speculative read context
+                void ctx.operatorCommands;
+                // @ts-expect-error strategy factories cannot capture radio command ports
+                void ctx.radioCommands;
+                throw new Error('type-only fixture');
+            },
+            isAutoCallEnabled: () => true,
+        });
+    });
+    it('keeps unload cleanup free of runtime command capabilities', () => {
+        definePlugin({
+            apiVersion: 2,
+            name: 'safe-cleanup',
+            version: '1.0.0',
+            type: 'utility',
+            permissions: ['operator:transmit-control', 'radio:control', 'network'],
+            onUnload(ctx) {
+                void ctx.store.global.flush();
+                ctx.timers.clearAll();
+                void ctx.files;
+                // @ts-expect-error unload cannot submit operator mutations
+                void ctx.operatorCommands;
+                // @ts-expect-error unload cannot control the physical radio
+                void ctx.radioCommands;
+                // @ts-expect-error unload cannot retain network capabilities
+                void ctx.network;
+            },
+            isAutoCallEnabled: () => true,
+        });
+    });
+    it('never exposes raw physical transmission primitives, even with command capabilities', () => {
+        definePlugin({
+            apiVersion: 2,
+            name: 'host-arbitrated-transmit-control',
+            version: '1.0.0',
+            type: 'utility',
+            permissions: ['operator:transmit-control', 'radio:read', 'radio:control', 'radio:power'],
+            hooks: {
+                async onUserAction(_actionId, _payload, ctx) {
+                    await ctx.operatorCommands.submit({ type: 'stop-automation' });
+                    await ctx.radioCommands.submit({ type: 'set-frequency', frequency: 14_074_000 });
+                    // @ts-expect-error physical PTT ownership is never a plugin capability
+                    void ctx.setPTT;
+                    // @ts-expect-error audio playback is owned by PhysicalTxCoordinator
+                    void ctx.playAudio;
+                    // @ts-expect-error frame mixing is an internal coordinator detail
+                    void ctx.audioMixer;
+                    // @ts-expect-error encoding is submitted through host intents only
+                    void ctx.encoder;
+                    // @ts-expect-error global emergency stop is reserved for authenticated host commands
+                    void ctx.forceStopTransmission;
+                },
+            },
+            isAutoCallEnabled: () => true,
+        });
+    });
+    it('requires an explicit tuner capability for tuner RF actions', () => {
+        definePlugin({
+            apiVersion: 2,
+            name: 'frequency-only',
+            version: '1.0.0',
+            type: 'utility',
+            permissions: ['radio:control'],
+            hooks: {
+                onUserAction(_actionId, _payload, ctx) {
+                    void ctx.radioCommands.submit({ type: 'set-frequency', frequency: 7_074_000 });
+                    // @ts-expect-error tuner RF actions require radio:tuner-control
+                    void ctx.radioTunerCommands;
+                },
+            },
+        });
+        definePlugin({
+            apiVersion: 2,
+            name: 'tuner-controller',
+            version: '1.0.0',
+            type: 'utility',
+            permissions: ['radio:tuner-control'],
+            hooks: {
+                onUserAction(_actionId, _payload, ctx) {
+                    void ctx.radioTunerCommands.submit({ type: 'start-manual-tune' });
+                    // @ts-expect-error tuner control does not grant frequency control
+                    void ctx.radioCommands;
+                },
+            },
+        });
+    });
+});
+//# sourceMappingURL=capability-context.test.js.map

package/dist/__tests__/capability-context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-context.test.js","sourceRoot":"","sources":["../../src/__tests__/capability-context.test.ts"],"names":[],"mappings":"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"}