@camstack/system 1.0.2

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs

@@ -0,0 +1,220 @@
+import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
+import { BaseAddon, EventCategory, addonWidgetsCapability, errMsg } from "@camstack/types";
+import { randomUUID } from "node:crypto";
+//#region src/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.ts
+/**
+* Addon Widgets Aggregator — hub-local builtin that owns the singleton
+* `addon-widgets` cap.
+*
+* Mirrors `addon-pages-aggregator` exactly: walks every registered
+* `addon-widgets-source` (collection) provider and emits an enriched
+* widget metadata list with versioned `bundleUrl`s pointing at
+* `/api/addon-widgets/<addonId>/<bundle>?v=<mtime>`. The filesystem
+* `mtime` cache-buster lets the browser pick up addon rebuilds without
+* manual reload.
+*
+* The static file endpoint (`/api/addon-widgets/:addonId/*`) is served
+* by `AddonWidgetsService.resolveBundle()` on the server side; this
+* addon only owns the listing surface.
+*
+* Why a builtin: same reasoning as `addon-pages-aggregator`. The
+* aggregator is the de-facto "addon-widgets provider" — addons own caps,
+* not the server. Living in `@camstack/system/builtins` keeps the surface
+* symmetrical with `system-config`, `local-auth`, etc.
+*/
+/**
+* Backoff schedule (ms) used to retry sources that failed during a
+* `listWidgets()` round-trip — typically because the cap was just
+* registered (provider connected via Moleculer) but the worker-side
+* action registration hadn't propagated yet, so `Service '...listWidgets'
+* is not found on '<node>'` raced ahead of the call.
+*
+* On success we re-emit `AddonWidgetReady` so admin-ui invalidates its
+* `addonWidgets.listWidgets` query and the registry populates without a
+* page reload.
+*/
+var RETRY_BACKOFF_MS = [
+	500,
+	1500,
+	4e3
+];
+/**
+* Per-source ceiling for a single `listWidgets()` round-trip. Mirrors the
+* addon-pages aggregator: a slow/unreachable source (e.g. an agent-hosted
+* widget source whose cap call sits in a Moleculer `waitForServices`) times
+* out fast and serves its cached snapshot instead of blocking the dashboard.
+*/
+var PER_SOURCE_TIMEOUT_MS = 2500;
+var AddonWidgetsAggregatorAddon = class extends BaseAddon {
+	id = "addon-widgets-aggregator";
+	resolvedPaths = null;
+	/**
+	* Last successful `listWidgets()` snapshot per source. Used as the
+	* "stale-but-valid" fallback when a source transiently fails — drops
+	* happen often enough during boot (Moleculer service-discovery
+	* window) that swallowing the error and returning empty would leave
+	* the dashboard with nothing for several seconds. Keeping the
+	* previous good entry means a flake is invisible to the operator.
+	*/
+	lastGood = /* @__PURE__ */ new Map();
+	/** In-flight retry guards keyed by sourceAddonId. Avoids double-scheduling. */
+	retryTimers = /* @__PURE__ */ new Map();
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		this.resolvedPaths = await this.resolvePaths();
+		const provider = { listWidgets: async () => this.aggregate() };
+		this.ctx.logger.info("Initialized — aggregating addon-widgets-source providers");
+		return [{
+			capability: addonWidgetsCapability,
+			provider
+		}];
+	}
+	async onShutdown() {
+		for (const t of this.retryTimers.values()) clearTimeout(t);
+		this.retryTimers.clear();
+		this.lastGood.clear();
+	}
+	/**
+	* Strip the `@<nodeId>` suffix that the CapabilityBridge appends to
+	* collection-provider registry keys for cross-node addons (see
+	* `moleculer.service.ts` — `registryKey = ${addonId}@${nodeId}`).
+	*
+	* The widget bundle is hub-resident (the same npm package ships to
+	* every node and the hub keeps a copy on disk keyed by the bare
+	* manifest id), so both the static-file URL and the admin-ui widget
+	* namespace must use the bare addon id. Without this, a widget
+	* source running on a remote agent yields a `bundleUrl` like
+	* `/api/addon-widgets/pipeline-analytics@agent-0/pipeline-analytics/remoteEntry.js`
+	* — the embedded `@<node>/<group>` makes the static-file route's
+	* `:addonId` param mismatch the registered provider and 404.
+	*/
+	bareAddonId(registryKey) {
+		const at = registryKey.indexOf("@");
+		return at === -1 ? registryKey : registryKey.slice(0, at);
+	}
+	async aggregate() {
+		const entries = this.capabilities?.getCollectionEntries("addon-widgets-source") ?? [];
+		const out = [];
+		const seenIds = /* @__PURE__ */ new Set();
+		const settled = await settleSourcesWithTimeout(entries.map(([registryKey, source]) => [registryKey, () => Promise.resolve(source.listWidgets())]), PER_SOURCE_TIMEOUT_MS);
+		for (const [addonId, result] of settled) {
+			const publicAddonId = this.bareAddonId(addonId);
+			seenIds.add(addonId);
+			if (result.ok) {
+				const enriched = result.value.map((w) => ({
+					...w,
+					addonId: publicAddonId,
+					bundleUrl: this.makeBundleUrl(publicAddonId, w.bundle)
+				}));
+				for (const item of enriched) out.push(item);
+				this.lastGood.set(addonId, enriched);
+			} else {
+				this.ctx.logger.warn("addon-widgets-source provider failed", { meta: {
+					sourceId: addonId,
+					error: result.error.message
+				} });
+				const cached = this.lastGood.get(addonId);
+				if (cached !== void 0) {
+					for (const item of cached) out.push(item);
+					this.ctx.logger.info("addon-widgets-source falling back to cached snapshot", { meta: {
+						sourceId: addonId,
+						cachedWidgets: cached.length
+					} });
+				}
+				this.scheduleRetry(addonId);
+			}
+		}
+		for (const cachedId of this.lastGood.keys()) if (!seenIds.has(cachedId)) this.lastGood.delete(cachedId);
+		return out;
+	}
+	scheduleRetry(sourceId, attempt = 0) {
+		if (attempt >= RETRY_BACKOFF_MS.length) return;
+		if (this.retryTimers.has(sourceId)) return;
+		const delayMs = RETRY_BACKOFF_MS[attempt] ?? RETRY_BACKOFF_MS[RETRY_BACKOFF_MS.length - 1];
+		const timer = setTimeout(() => {
+			this.retryTimers.delete(sourceId);
+			this.retrySource(sourceId, attempt);
+		}, delayMs);
+		this.retryTimers.set(sourceId, timer);
+	}
+	async retrySource(sourceId, attempt) {
+		const found = (this.capabilities?.getCollectionEntries("addon-widgets-source") ?? []).find(([id]) => id === sourceId);
+		if (!found) return;
+		const [addonId, source] = found;
+		const publicAddonId = this.bareAddonId(addonId);
+		try {
+			const enriched = (await Promise.resolve(source.listWidgets())).map((w) => ({
+				...w,
+				addonId: publicAddonId,
+				bundleUrl: this.makeBundleUrl(publicAddonId, w.bundle)
+			}));
+			this.lastGood.set(addonId, enriched);
+			this.ctx.logger.info("addon-widgets-source recovered after retry", { meta: {
+				sourceId: addonId,
+				attempt: attempt + 1,
+				widgets: enriched.length
+			} });
+			this.ctx.eventBus.emit({
+				id: randomUUID(),
+				timestamp: /* @__PURE__ */ new Date(),
+				source: {
+					type: "addon",
+					id: this.id
+				},
+				category: EventCategory.AddonWidgetReady,
+				data: {
+					addonId: publicAddonId,
+					recovered: true
+				}
+			});
+		} catch (err) {
+			this.ctx.logger.debug("addon-widgets-source retry failed", { meta: {
+				sourceId,
+				attempt: attempt + 1,
+				error: errMsg(err)
+			} });
+			this.scheduleRetry(sourceId, attempt + 1);
+		}
+	}
+	/**
+	* Build `/api/addon-widgets/<addonId>/<bundle>?v=<mtime>`. Falls back
+	* to `Date.now()` when the bundle path can't be stat'd (remote addon
+	* with no local file, addon not yet on disk, etc.) — the browser
+	* just gets a fresh URL on each call instead of cache-friendly mtime.
+	*/
+	makeBundleUrl(addonId, bundle) {
+		const bundlePath = this.resolveBundlePath(addonId, bundle);
+		let mtime = Date.now();
+		if (bundlePath !== null) try {
+			mtime = fs.statSync(bundlePath).mtimeMs;
+		} catch {}
+		return `/api/addon-widgets/${addonId}/${bundle}?v=${Math.floor(mtime)}`;
+	}
+	resolveBundlePath(addonId, bundle) {
+		const paths = this.resolvedPaths;
+		if (!paths) return null;
+		const addonDistPath = path$1.join(paths.addonsDir, "@camstack", `addon-${addonId}`, "dist");
+		const resolvedBase = path$1.resolve(addonDistPath);
+		const resolvedFile = path$1.resolve(addonDistPath, bundle);
+		if (!resolvedFile.startsWith(resolvedBase + path$1.sep) && resolvedFile !== resolvedBase) return null;
+		return resolvedFile;
+	}
+	async resolvePaths() {
+		const fallback = { addonsDir: path$1.resolve("camstack-data", "addons") };
+		if (!this.ctx.settings) return fallback;
+		try {
+			const server = await this.ctx.settings.getSection("server");
+			const dataPath = typeof server["dataPath"] === "string" && server["dataPath"] ? server["dataPath"] : "camstack-data";
+			return { addonsDir: path$1.resolve(dataPath, "addons") };
+		} catch (err) {
+			this.ctx.logger.debug("Failed to read server.dataPath — falling back", { meta: { error: errMsg(err) } });
+			return fallback;
+		}
+	}
+};
+//#endregion
+export { AddonWidgetsAggregatorAddon, AddonWidgetsAggregatorAddon as default };

package/dist/builtins/addon-widgets-aggregator/index.d.ts

@@ -0,0 +1 @@
+export { AddonWidgetsAggregatorAddon, default } from './addon-widgets-aggregator.addon.js';

package/dist/builtins/addon-widgets-aggregator/index.js

@@ -0,0 +1,8 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Cek0wNdY.js");
+const require_builtins_addon_widgets_aggregator_addon_widgets_aggregator_addon = require("./addon-widgets-aggregator.addon.js");
+exports.AddonWidgetsAggregatorAddon = require_builtins_addon_widgets_aggregator_addon_widgets_aggregator_addon.AddonWidgetsAggregatorAddon;
+exports.default = require_builtins_addon_widgets_aggregator_addon_widgets_aggregator_addon.AddonWidgetsAggregatorAddon;

package/dist/builtins/addon-widgets-aggregator/index.mjs

@@ -0,0 +1,2 @@
+import { AddonWidgetsAggregatorAddon } from "./addon-widgets-aggregator.addon.mjs";
+export { AddonWidgetsAggregatorAddon, AddonWidgetsAggregatorAddon as default };

package/dist/builtins/alerts/alerts.addon.d.ts

@@ -0,0 +1,81 @@
+import { ProviderRegistration, Alert, BaseAddon } from '@camstack/types';
+interface AlertCenterConfig {
+    readonly maxAlerts: number;
+    readonly retentionDays: number;
+}
+/**
+ * Alert Center addon — core builtin that persists alerts in a
+ * structured SQLite table and serves them to the admin UI.
+ *
+ * Registers as an `alerts` collection provider and subscribes to
+ * important EventBus categories to create/update alerts automatically.
+ */
+export declare class AlertCenterAddon extends BaseAddon<AlertCenterConfig> {
+    private unsubscribers;
+    constructor();
+    /**
+     * Per `(category, source.id)` counter used to rate-limit chatty
+     * events. Entries are pruned lazily when they age out of
+     * `RATE_LIMIT_WINDOW_MS`; see `shouldSuppressByRate()` below.
+     */
+    private readonly rateLimitCounters;
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
+    listAlerts(filter?: {
+        unreadOnly?: boolean;
+        limit?: number;
+    }): Promise<readonly Alert[]>;
+    getUnreadCount(): Promise<number>;
+    markRead(alertId: string): Promise<void>;
+    markAllRead(): Promise<void>;
+    dismiss(alertId: string): Promise<void>;
+    private handleEvent;
+    private handleModelDownload;
+    /**
+     * `[ALERT-CENTER-EVENTS]` — rate limit a `(category, source.id)`
+     * tuple. Returns `true` when the caller should DROP this event
+     * without persisting an alert, and `false` when the alert should
+     * proceed normally.
+     *
+     * Heuristic: the first `RATE_LIMIT_MAX_PER_SOURCE` events within a
+     * `RATE_LIMIT_WINDOW_MS` window go through. Once the threshold is
+     * crossed, subsequent events are suppressed until the window rolls
+     * over. When the threshold is first crossed, the suppression is
+     * logged once so operators know why they're not seeing the follow-
+     * up alerts; after the window rolls over the next event is
+     * un-suppressed and starts a new window.
+     */
+    private shouldSuppressByRate;
+    /**
+     * AddonLoadFailed — kernel's AddonHealthMonitor has post-grace
+     * failed an addon load/init. Upsert a stable-id alert keyed by
+     * `addon-load-failed:<packageName>` so the recovery path can
+     * dismiss it. Severity=error, persistent until dismissed or
+     * auto-resolved.
+     *
+     * The action `retry` carries the package name so the admin UI can
+     * dispatch `addons.retryLoad(packageName)` directly from the alert
+     * card without the operator opening the Addons page.
+     */
+    private handleAddonLoadFailed;
+    /**
+     * AddonLoadRecovered — addon previously alerting is back to healthy.
+     * Dismiss the matching alert so the operator's badge count drops.
+     */
+    private handleAddonLoadRecovered;
+    private buildMessage;
+    private emitAlert;
+    private updateAlert;
+    /**
+     * Read-merge-write: SettingsBackend.update() replaces the entire `data` blob,
+     * so we must read the existing record, merge the patch, and write back.
+     */
+    private mergeUpdate;
+    private persistAlert;
+    private emitAlertCreatedEvent;
+    private emitAlertUpdatedEvent;
+    private enforceMaxAlerts;
+    private enforceRetention;
+}
+export default AlertCenterAddon;