@camstack/system 1.0.2

package/dist/lifecycle/lifecycle-state-machine.d.ts

@@ -0,0 +1,28 @@
+import { IScopedLogger, IEventBus } from '@camstack/types';
+export type ElementState = 'stopped' | 'starting' | 'running' | 'stopping' | 'error' | 'disabled';
+export interface ElementStatus {
+    state: ElementState;
+    error?: string;
+    startedAt?: number;
+    stoppedAt?: number;
+    restartCount: number;
+    uptime: number;
+}
+export declare class LifecycleStateMachine {
+    private readonly elementId;
+    private readonly elementType;
+    private readonly eventBus;
+    private readonly logger;
+    private _state;
+    private _error?;
+    private _startedAt?;
+    private _stoppedAt?;
+    private _restartCount;
+    private _hasStartedOnce;
+    constructor(elementId: string, elementType: 'provider' | 'device' | 'addon' | 'process', eventBus: IEventBus, logger: IScopedLogger);
+    get state(): ElementState;
+    getStatus(): ElementStatus;
+    transition(to: ElementState, error?: string): boolean;
+    incrementRestartCount(): void;
+    private isValidTransition;
+}

package/dist/logging/formatter.d.ts

@@ -0,0 +1,30 @@
+import { LogEntry } from '@camstack/types';
+/** Options for `formatLogLine`. */
+export interface FormatLogLineOptions {
+    /**
+     * Emit ANSI colour codes. When omitted, falls back to the shell-env
+     * heuristic (`NO_COLOR`/`FORCE_COLOR`/`isTTY`). Destinations that
+     * always target a console (ConsoleDestination, HubForwarderDestination)
+     * pass `true`; file sinks (Winston JSON) pass `false` so logs on disk
+     * stay plain text regardless of the shell env.
+     *
+     * `NO_COLOR=1` in the environment still wins — consumer opt-in beats
+     * producer opt-in, matching the https://no-color.org/ convention.
+     */
+    readonly colorize?: boolean;
+}
+/**
+ * Render a `LogEntry` as one complete console line — no trailing newline.
+ * Caller appends `\n` (file sinks) or relies on `console.log` (stdout sink).
+ *
+ * PID column prefers `entry.tags.pid` when set (so forked-worker entries
+ * carry the worker's OS pid even when the hub renders them), falling back
+ * to the renderer's own `process.pid`.
+ *
+ * Colours (when enabled) follow the NestJS convention: the level token
+ * AND the message body share the level colour (green/yellow/red/gray for
+ * info/warn/error/debug). Brand, device context, scope and meta keep
+ * their fixed hues so the structural fields stay visually distinct from
+ * the message content.
+ */
+export declare function formatLogLine(entry: LogEntry, options?: FormatLogLineOptions): string;

package/dist/logging/log-manager.d.ts

@@ -0,0 +1,54 @@
+import { LogEntry, LogFilter } from './log-ring-buffer.js';
+import { IScopedLogger } from './scoped-logger.js';
+export interface ILogDestination {
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    write(entry: LogEntry): void;
+    query?(filter: LogFilter): Promise<readonly LogEntry[]>;
+}
+export declare class LogManager {
+    private readonly ringBuffer;
+    private readonly destinations;
+    private readonly subscribers;
+    private deviceNameLookup;
+    /** `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty
+     *  addon evicts only its own lines, so quiet addons keep their sparse history.
+     *  See {@link PartitionedLogBuffer}. */
+    constructor(perAddonCapacity?: number);
+    /**
+     * Register a callback that resolves `deviceId → deviceName`. Called
+     * for every emitted entry that carries `tags.deviceId` but no
+     * explicit `tags.deviceName` — the LogManager injects the resolved
+     * name directly into the entry's tags BEFORE ring-buffer / destination
+     * write, so every destination (local console, file, remote forwarder,
+     * addon-bundled copies of core) sees the enriched shape regardless of
+     * which module instance the destination was built from.
+     */
+    setDeviceNameLookup(lookup: ((deviceId: number) => string | null) | null): void;
+    createLogger(scope?: string): IScopedLogger;
+    private enrichDeviceName;
+    /** Subscribe to live logs matching a filter. Returns an unsubscribe function. */
+    subscribe(filter: Partial<LogFilter>, callback: (entry: LogEntry) => void): () => void;
+    private matchesFilter;
+    /**
+     * Register a log destination.
+     *
+     * @param opts.replay  If true (default), replay every entry currently in
+     *                     the ring buffer to the new destination before live
+     *                     traffic starts. Lets a destination added mid-boot
+     *                     still receive boot-time log entries.
+     */
+    addDestination(dest: ILogDestination, opts?: {
+        replay?: boolean;
+    }): void;
+    removeDestination(dest: ILogDestination): void;
+    query(filter: LogFilter): LogEntry[];
+    /**
+     * Drop ring-buffer entries matching `filter`. Returns the count
+     * removed. Backs the UI's "Clear logs" admin action so an operator
+     * can wipe the historical window for a scope (per-device, per-addon,
+     * agent-level) without restarting the server. External destinations
+     * (file, forwarder) are NOT touched — only the in-memory ring.
+     */
+    clear(filter?: LogFilter): number;
+}

package/dist/logging/log-ring-buffer.d.ts

@@ -0,0 +1,47 @@
+import { LogLevel, LogEntry, LogFilter, LogTags } from '@camstack/types';
+export type { LogLevel, LogEntry, LogFilter };
+/**
+ * Per-tag filter matcher with semantic-aware comparisons:
+ *
+ *   `addonId`  — matches the entry's bare addon id (strips any `@<workerId>`
+ *                qualifier added by the cap-router for remote providers).
+ *                So a UI filter for `audio-classifier` matches both the
+ *                addon's own log lines and bridge management lines whose
+ *                addonId is logged as `audio-classifier@dev-agent-0/audio-classifier`.
+ *
+ *   `agentId`  — matches when ANY of these hold:
+ *                  * the entry was emitted by that agent (`agentId` exact)
+ *                  * the entry's `nodeId` IS that agent (single-node case)
+ *                  * the entry's `nodeId` starts with `<agent>/` (worker
+ *                    inside that agent — e.g. `dev-agent-0/audio-classifier`)
+ *                Captures all the log emission paths for an addon hosted
+ *                on the agent regardless of who actually emitted the line.
+ *
+ *   any other key — exact match (legacy semantics).
+ *
+ * Returns `true` when ALL filter keys match (AND), `false` otherwise.
+ * `undefined` filter values are skipped.
+ */
+export declare function matchesLogTags(entryTags: LogTags | undefined, filterTags: Partial<LogTags>): boolean;
+export declare class LogRingBuffer {
+    private readonly capacity;
+    private readonly buffer;
+    private head;
+    private count;
+    constructor(capacity?: number);
+    push(entry: LogEntry): void;
+    getAll(): LogEntry[];
+    query(filter: LogFilter): LogEntry[];
+    /**
+     * Drop entries that match `filter`. Returns the number of entries
+     * removed. Triggered by the UI's "Clear logs" button so the operator
+     * can wipe the historical buffer for a specific scope (per-device,
+     * per-addon, per-agent) — without it, closing and reopening the
+     * panel re-populates the cleared rows from the server's ring buffer.
+     *
+     * Filter semantics mirror `query` (same level / since / until / tags
+     * handling) — whatever you'd see listed by `query(filter)` is what
+     * gets removed.
+     */
+    clear(filter?: LogFilter): number;
+}

package/dist/logging/partitioned-log-buffer.d.ts

@@ -0,0 +1,35 @@
+import { LogEntry, LogFilter } from '@camstack/types';
+/**
+ * A log buffer partitioned into one fixed-capacity {@link LogRingBuffer} per
+ * `addonId`. A chatty addon (e.g. detection-pipeline) only ever evicts its OWN
+ * bucket, so a quiet addon's sparse lines (e.g. a HomeAssistant `image` entity)
+ * survive far longer than they would in a single shared FIFO ring.
+ *
+ * Drop-in for {@link LogRingBuffer} from {@link LogManager}'s perspective —
+ * exposes the same `push` / `getAll` / `query` / `clear` surface. Total memory
+ * is bounded by `perAddonCapacity × (number of distinct addons seen)`; quiet
+ * buckets never grow past the handful of lines they actually emit.
+ */
+export declare class PartitionedLogBuffer {
+    private readonly perAddonCapacity;
+    private readonly buffers;
+    constructor(perAddonCapacity?: number);
+    private bufferFor;
+    push(entry: LogEntry): void;
+    /** Every retained entry across all buckets, newest-first (mirrors
+     *  {@link LogRingBuffer.getAll}). Used to replay history to a destination. */
+    getAll(): LogEntry[];
+    /**
+     * Query across buckets. When the filter pins an `addonId`, only that addon's
+     * bucket is scanned (the common case — the device/addon Logs tab). Otherwise
+     * every bucket is scanned, merged newest-first, then limited — so a
+     * `deviceId`-only filter (a device's own Logs tab) still finds its lines
+     * regardless of which addon emitted them.
+     */
+    query(filter: LogFilter): LogEntry[];
+    clear(filter?: LogFilter): number;
+    /** The bucket key a filter pins to via `tags.addonId`, or null when the
+     *  filter doesn't constrain the addon (→ scan all buckets). */
+    private pinnedAddonKey;
+    private mergeNewestFirst;
+}

package/dist/logging/scoped-logger.d.ts

@@ -0,0 +1,17 @@
+import { IScopedLogger, LogExtras, LogTags } from '@camstack/types';
+import { LogEntry } from './log-ring-buffer.js';
+export type { IScopedLogger };
+export declare class ScopedLogger implements IScopedLogger {
+    private readonly scope;
+    private readonly writeFn;
+    private readonly tags?;
+    constructor(scope: string | undefined, writeFn: (entry: LogEntry) => void, tags?: LogTags | undefined);
+    debug(message: string, extras?: LogExtras): void;
+    info(message: string, extras?: LogExtras): void;
+    warn(message: string, extras?: LogExtras): void;
+    error(message: string, extras?: LogExtras): void;
+    child(childScope: string): IScopedLogger;
+    withTags(tags: LogTags): IScopedLogger;
+    private write;
+    private mergeTags;
+}