@camstack/system 1.1.11 → 1.1.13

package/dist/addon-runner.mjs

@@ -1,4 +1,4 @@
-import { $ as setWorkerNativeCapsChangeListener, A as createUdsLoggerWithControl, X as getWorkerNativeCapProvider, Z as getWorkerNativeCapSnapshot, i as createUdsAddonContext, j as LocalChildClient, mt as resolveAddonClass, pt as installManifestNativeDeps, t as installManifestPythonDeps, tt as validateProviderRegistrations } from "./manifest-python-deps-1zTy3vXe.mjs";
+import { $ as setWorkerNativeCapsChangeListener, A as createUdsLoggerWithControl, X as getWorkerNativeCapProvider, Z as getWorkerNativeCapSnapshot, i as createUdsAddonContext, j as LocalChildClient, mt as resolveAddonClass, pt as installManifestNativeDeps, t as installManifestPythonDeps, tt as validateProviderRegistrations } from "./manifest-python-deps-BfJEdXhi.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-BEXwC-oo.mjs";
 import { register } from "node:module";
 import * as fs from "node:fs";

package/dist/builtins/device-manager/device-aggregation-merge.d.ts

@@ -0,0 +1,22 @@
+import { ConfigUISchemaWithValues } from '@camstack/types';
+import { ContributionShape } from './device-meta-types.js';
+/**
+ * Walk the sections/fields of a contribution and inject `writerCapName` +
+ * `writerAddonId` + `source` on each editable field. Readonly fields and
+ * structural fields (separator/info/button) pass through untouched. The
+ * aggregator is the single place that knows provenance — provider schemas
+ * stay clean, UI-bound metadata is attached once at the boundary.
+ */
+export declare function tagContribution(contribution: ContributionShape, capName: string, addonId: string, kind: 'settings' | 'live'): ContributionShape;
+export declare function isFieldRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Convert a strict `ConfigUISchemaWithValues` (readonly arrays, typed
+ * field union) into the cap wire shape `ContributionShape` (mutable
+ * arrays, opaque field records). Required because the cap method z.infer
+ * uses mutable arrays — readonly arrays are not assignable to mutable
+ * even when structurally identical, so a structural copy bridges the gap
+ * without disabling the type checker.
+ */
+export declare function toWireShape(input: ConfigUISchemaWithValues): ContributionShape;
+export declare function tagField(field: unknown, capName: string, addonId: string, source: 'settings' | 'live', kind: 'settings' | 'live'): unknown;
+export declare function mergeAggregates(parts: readonly ContributionShape[]): ContributionShape;

package/dist/builtins/device-manager/device-aggregation.d.ts

@@ -0,0 +1,220 @@
+import { deviceManagerCapability, InferProvider, AddonContext, CapabilityDefinition, DeviceBindingEntry, DeviceConfigSpec, DeviceSettingsContribution, ICapabilityRegistry, IDevice } from '@camstack/types';
+import { ContributionShape, DriverConfigSchemaResult } from './device-meta-types.js';
+import { BindingsDeps, RemoteNativeCaps } from './device-bindings-store.js';
+/**
+ * Dependencies the aggregation + update routing functions consume. Assembled
+ * by the addon from its own state and passed in explicitly — no hidden `this`
+ * capture. `bindingsDeps` carries the lower-level context the bindings-store
+ * resolvers need so this module can call them directly.
+ */
+export interface AggregationDeps {
+    readonly ctx: AddonContext;
+    readonly capabilityRegistry: ICapabilityRegistry | undefined;
+    readonly remoteNativeCaps: RemoteNativeCaps;
+    readonly bindingsDeps: BindingsDeps;
+}
+type IDeviceManagerProvider = InferProvider<typeof deviceManagerCapability>;
+export declare function getDeviceAggregate(deps: AggregationDeps, deviceId: number, kind: 'settings' | 'live'): Promise<ContributionShape | null>;
+/**
+ * System-scoped per-device contributions — the deliberate exception to
+ * binding-driven aggregation (D12).
+ *
+ * A `scope: 'system'` cap with `exposesDeviceSettings: true` holds per-device
+ * state but is NOT bound per-device: it is a system addon, not a BaseDevice,
+ * so it never calls `registerNativeCap` and never appears in
+ * `getBindings(deviceId)`. The binding-driven loop therefore skips it and its
+ * per-device panel never renders. Two such caps ship today:
+ *   - `stream-broker` (singleton) — the RTSP-restream / pre-buffer settings
+ *     tab, scoped to the cameras whose streams it serves.
+ *   - `device-export` (collection) — the "Export" panel; a device can be
+ *     exposed to MULTIPLE exporters at once (Alexa + HomeKit + HA-MQTT).
+ *
+ * D12 bans fanning a per-device call out to every same-named provider of a
+ * `scope: 'device'` cap, because vendor providers SHARE cap names
+ * (`stream-params`/`ptz` from reolink AND hikvision). System caps are NOT
+ * vendor-shared — a system cap name maps to one active provider (singleton)
+ * or one declared collection — so consulting the cap's own provider(s)
+ * directly is safe. Each provider gates internally by deviceId and returns
+ * null for devices it does not own.
+ *
+ * `seenCaps` skips any system cap that already contributed via a binding so
+ * its section is never duplicated.
+ */
+export declare function collectSystemDeviceContributions(deps: AggregationDeps, deviceId: number, kind: 'settings' | 'live', seenCaps: ReadonlySet<string>): Promise<ContributionShape[]>;
+/**
+ * D14: framework-derived device-config contribution.
+ *
+ * `kind === 'live'` — device-config caps contribute nothing to the live
+ * aggregate (they hold editable config, not live observables).
+ *
+ * `ui.kind === 'widget'` — emits a single structural `type:'widget'`
+ * section; the widget self-persists via the cap's own mutations.
+ *
+ * `ui.kind === 'derived-form'` — calls `getOptions`/`getStatus` on the
+ * bound provider, runs the registered pure builder, and returns the
+ * derived form sections. Returns null when the camera exposes nothing
+ * configurable or the provider is not yet registered.
+ */
+export declare function deriveDeviceConfigContribution(deps: AggregationDeps, registry: ICapabilityRegistry, def: CapabilityDefinition & {
+    deviceConfig: DeviceConfigSpec;
+}, entry: DeviceBindingEntry, deviceId: number, kind: 'settings' | 'live'): Promise<ContributionShape | null>;
+/**
+ * Build the device-manager's own contribution to the aggregator — the
+ * device identity (id, stableId, addonId, type, online) + the
+ * driver-specific config exposed by the device class via
+ * `zodEntriesToConfigUI`.
+ *
+ * Two paths, deliberately symmetric with `getSettingsSchema`:
+ *
+ *  - Hub-local: device's IDevice instance lives in this process'
+ *    DeviceRegistry, we read config + schema directly by reference.
+ *  - Cross-process: device lives in a forked worker (RtspCamera on
+ *    provider-rtsp, ONVIF on provider-onvif, …). We ask the worker's
+ *    `device-ops.getSettingsSchema` native provider for a wire-
+ *    serializable ConfigUISchema and merge it in under the same
+ *    "Driver Config" section, so the UI sees the same shape regardless
+ *    of where the IDevice physically runs.
+ *
+ *  Returns `null` only when the device genuinely doesn't exist anywhere
+ *  (no hub-local, no persisted ownership, no device-ops native). The
+ *  aggregator falls back to contributor sections only in that case.
+ */
+export declare function buildBaseDeviceSection(deps: AggregationDeps, deviceId: number): Promise<ContributionShape | null>;
+/**
+ * Lookup the native owner for `device-ops` on `deviceId` — the native-cap
+ * registry (hub-local and remote) is keyed by numeric id.
+ */
+export declare function resolveNativeDeviceOwner(deps: AggregationDeps, deviceId: number): {
+    addonId: string;
+    nodeId: string;
+} | null;
+/**
+ * Aggregate `status` across every registered cap for a device.
+ *
+ * Walks the supplied cap list (or `CAP_NAMES_WITH_STATUS` when
+ * omitted), looks up a native provider per cap via the capability
+ * registry, calls `provider.getStatus({ deviceId })`, and validates
+ * the return against the cap's own `status.schema`. Validation
+ * failures log a warning and yield `null` for that cap so the
+ * overall aggregate stays usable — a single misbehaving provider
+ * must not blank out a device's entire status view.
+ *
+ * Returned shape is `Record<capName, unknown | null>`; the client-
+ * side hook tightens this to `CapStatusTypeMap` via the generated
+ * `cap-status-types.ts`.
+ */
+export declare function getDeviceStatusAggregate(deps: AggregationDeps, input: {
+    readonly deviceId: number;
+    readonly caps?: readonly string[];
+}): Promise<Record<string, unknown | null>>;
+/**
+ * Return the driver-specific device-settings contribution. Hub-local
+ * devices call `getSettingsUISchema()` directly; forked-worker devices
+ * go through the `device-ops.getSettingsSchema` cap method on the
+ * numeric-id-keyed native registry.
+ *
+ * Returns a discriminated result so callers can distinguish three states:
+ *   'ok'          – schema obtained successfully
+ *   'none'        – driver genuinely has no settings schema
+ *   'unavailable' – worker was unreachable after retries (transient)
+ */
+export declare function resolveDriverConfigSchema(deps: AggregationDeps, deviceId: number, hubLocal: {
+    addonId: string;
+    device: IDevice;
+} | null): Promise<DriverConfigSchemaResult>;
+export declare function updateDeviceField(deps: AggregationDeps, input: {
+    deviceId: number;
+    writerCapName: string;
+    writerAddonId: string;
+    key: string;
+    value: unknown;
+}): Promise<{
+    success: true;
+}>;
+/**
+ * Dispatch a device custom action. Hub-local devices run it directly;
+ * forked/remote devices route through the `device-ops` native cap
+ * (`runAction`) — the same hub-local-then-device-ops fan-out that
+ * `updateDeviceField` uses for `applySettingsPatch`.
+ */
+export declare function dispatchDeviceAction(deps: AggregationDeps, deviceId: number, action: string, input: unknown): Promise<unknown>;
+/**
+ * Resolve the `DeviceSettingsContribution` provider that owns a tagged
+ * field. The `writerAddonId` on a tagged field equals `entry.providerAddonId`
+ * from the binding that produced it — for `kind:'wrapped'` entries, that is
+ * the wrapper addon id (e.g. 'snapshot-addon'); for native-only entries,
+ * the system addon id.
+ *
+ * Resolution order (Bug-3 fix):
+ *  1. `getProviderByAddon(capName, writerAddonId)` — resolves the
+ *     system-registered provider by the addon id from the tagged field.
+ *     For wrapper bindings (snapshot, motion-detection, etc.) this directly
+ *     returns the wrapper provider, bypassing the native-first resolution
+ *     order of `getProviderForDevice` that caused "method not found".
+ *  2. `getSingleton(capName)` — fallback for stale/mismatched writerAddonIds.
+ *     The active singleton handles the contribution even if the addonId
+ *     stored in the field is out of date (e.g. after an addon rename).
+ *
+ * `getProviderForDevice` is intentionally NOT used here: it returns the
+ * per-device native first when present (e.g. Reolink/ONVIF), and the native
+ * does NOT implement contribution methods — the root cause of Bug-3.
+ */
+export declare function resolveContributionProvider(registry: ICapabilityRegistry, _def: CapabilityDefinition, writerCapName: string, writerAddonId: string, deviceId: number): DeviceSettingsContribution;
+/**
+ * Batched counterpart of `updateDeviceField`. Groups changes by
+ * `(writerCapName, writerAddonId)` so each contributor receives a
+ * single `applyDeviceSettingsPatch` with all of its updates merged —
+ * avoids N round-trips for simultaneous edits in the same save.
+ *
+ * Per-provider failures are captured in the `failures[]` output so the
+ * admin UI can highlight which sections didn't persist; a failure on
+ * one provider does NOT abort the others.
+ */
+export declare function updateDeviceFieldsBatch(deps: AggregationDeps, input: {
+    deviceId: number;
+    changes: ReadonlyArray<{
+        writerCapName: string;
+        writerAddonId: string;
+        key: string;
+        value: unknown;
+    }>;
+}): Promise<{
+    success: true;
+    failures: {
+        writerCapName: string;
+        writerAddonId: string;
+        error: string;
+    }[];
+}>;
+/** Apply a single grouped patch to the appropriate provider. Mirrors
+ * `updateDeviceField` routing (special-case device-manager, else
+ * registry lookup). Used by `updateDeviceFieldsBatch`. */
+export declare function applyGroupPatch(deps: AggregationDeps, deviceId: number, group: {
+    writerCapName: string;
+    writerAddonId: string;
+    patch: Record<string, unknown>;
+}): Promise<void>;
+export declare function listWrappersForCap(deps: AggregationDeps, input: {
+    capName: string;
+}): Promise<string[]>;
+export declare function listBindableCapsForDeviceType(deps: AggregationDeps, input: {
+    deviceType: string;
+}): Promise<Array<{
+    capName: string;
+    wrappers: string[];
+}>>;
+export declare function setWrapperActive(deps: AggregationDeps, input: {
+    deviceId: number;
+    capName: string;
+    wrapperAddonId: string;
+    active: boolean;
+}): Promise<void>;
+/**
+ * Per-device wireable-field catalog — the domain status fields a device's
+ * bound caps expose, for the operator's cross-device wiring UI. Binding-driven:
+ * walks `getBindings(deviceId)`, skips wrapper caps (their status schemas are
+ * internal book-keeping, not wireable domain data), and enumerates each cap's
+ * status schema leaf fields. Behavior unchanged from the inline provider method.
+ */
+export declare function getWireableFields(deps: AggregationDeps, input: Parameters<IDeviceManagerProvider['getWireableFields']>[0]): ReturnType<IDeviceManagerProvider['getWireableFields']>;
+export {};

package/dist/builtins/device-manager/device-bindings-store.d.ts

@@ -0,0 +1,100 @@
+import { AddonContext, DeviceBindingEntry, ICapabilityRegistry } from '@camstack/types';
+import { DeviceBindingsStore } from './device-meta-types.js';
+/** Push-fed remote native-cap cache shape (numeric deviceId → capName → owner). */
+export type RemoteNativeCaps = Map<number, Map<string, {
+    addonId: string;
+    nodeId: string;
+}>>;
+/**
+ * Low-level dependencies the binding resolver needs. Assembled by the addon
+ * from its own (mostly private) state and passed in explicitly — no hidden
+ * `this` capture.
+ */
+export interface BindingsDeps {
+    readonly ctx: AddonContext;
+    readonly capabilityRegistry: ICapabilityRegistry | undefined;
+    readonly remoteNativeCaps: RemoteNativeCaps;
+}
+/**
+ * Wire the push-fed cross-process native-cap cache (`remoteNativeCaps`).
+ * Workers emit `DeviceBindingsChanged` on `ctx.registerNativeCap` / device
+ * removal; we mirror those into `remoteNativeCaps` so `getBindings` returns the
+ * full cluster view. Events from the local node are ignored: hub-local natives
+ * live in `capabilityRegistry` and are folded in directly by getBindings.
+ *
+ * Push events are accurate in the steady state but can be lost during the
+ * Moleculer transport handshake window (hub restart, crash-respawn,
+ * restartAddon). The reliable replacement for lost events is the D3 re-handshake
+ * (`listClusterNativeCaps()`), which `resolveNativeCapOwnerSync` /
+ * `getBindings` step 4 fall through to on a push miss. The `$node.disconnected`
+ * handler purges a gone node's entries; the worker re-handshakes (and re-emits
+ * `native-registered`) on its next boot.
+ */
+export declare function wireRemoteNativeCapSync(ctx: AddonContext, remoteNativeCaps: RemoteNativeCaps): void;
+export declare function readBindingsStore(deps: BindingsDeps): Promise<DeviceBindingsStore>;
+export declare function writeBindingsStore(deps: BindingsDeps, next: DeviceBindingsStore): Promise<void>;
+export declare function resolveWrapperNodeId(_wrapperAddonId: string): string;
+/**
+ * Reduce a provider node id to the routable form `DeviceProxy` can pin.
+ *
+ * Every addon runs in its own `addon-runner` with the composite node id
+ * `${parentNodeId}/${runnerId}` (see `addon-runner.ts`) — e.g.
+ * `hub/provider-reolink` or `dev-agent-0/provider-reolink`. That composite is
+ * an IDENTITY, not a routable target: the `CapRouteResolver` reaches a child
+ * only THROUGH its parent (the hub resolves a hub-local-uds child by
+ * cap+device; an agent forwards to its own child). `DeviceProxy` pins
+ * `entry.providerNodeId` on every cap call, so a binding entry must expose the
+ * parent node id — otherwise the explicit pin classifies as `remote-moleculer`
+ * to an unknown node → `no-provider`, which surfaces as
+ * "this camera doesn't expose …" for client-proxy-driven widget caps
+ * (motion-zones, privacy-mask). Wrappers already report the parent via
+ * `resolveWrapperNodeId`; this aligns natives with the same contract.
+ *
+ * A flat node id (a genuine standalone node with no `/`) is returned
+ * unchanged.
+ */
+export declare function toRoutableProviderNodeId(nodeId: string): string;
+/**
+ * Resolve a remote native cap entry for a given `(capName, deviceId)` by
+ * consulting the handshake-fed `HubNodeRegistry` via
+ * `ctx.kernel.listClusterNativeCaps()`. Called when the push-based
+ * `remoteNativeCaps` cache misses — covers the Moleculer transport
+ * handshake window where `DeviceBindingsChanged` events were lost but the
+ * D3 re-handshake (post device restore) has already populated the registry.
+ *
+ * Returns `null` when the entry is genuinely not present in the cluster
+ * view (cap not registered on any worker for that device).
+ */
+export declare function resolveRemoteNativeCapFromRegistry(deps: BindingsDeps, capName: string, deviceId: number): {
+    addonId: string;
+    nodeId: string;
+} | null;
+export declare function getBindings(deps: BindingsDeps, input: {
+    deviceId: number;
+}): Promise<{
+    deviceId: number;
+    entries: DeviceBindingEntry[];
+}>;
+/**
+ * Whole-fleet binding dump. Iterates every device known to the
+ * deviceRegistry and reuses the per-device `getBindings` resolver
+ * for each — same routing rules, single round-trip. Used by
+ * `SystemManager.init()` for warm-boot.
+ *
+ * Bindings change rarely (wrapper toggle, device add/remove) so
+ * clients invalidate via the existing
+ * `capability.binding-changed` event rather than re-fetching this
+ * payload periodically.
+ */
+export declare function getAllBindings(deps: BindingsDeps): Promise<Array<{
+    deviceId: number;
+    entries: DeviceBindingEntry[];
+}>>;
+/**
+ * Resolve a numeric deviceId to a stableId via persisted meta.
+ * Used only by the device-identity section of the device-details
+ * aggregator (see `buildBaseDeviceSection`) to surface the stableId as
+ * a readonly display field. All runtime/registry lookups are keyed by
+ * numeric deviceId; this helper is display-only.
+ */
+export declare function lookupPersistedStableId(deps: BindingsDeps, deviceId: number): Promise<string | undefined>;