@camstack/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+import { ModelDownloadOptions, ModelDownloadResult, IPythonEnvironment, PythonProbeResult, PythonEnvReady, AddonDeclaration, ICamstackAddon, AddonContext, PipelineConfig, FrameInput, PipelineResult } from '@camstack/types';
+import { ChildProcess } from 'node:child_process';
+
+type EventCallback<T = unknown> = (data: T) => void;
+declare class EventBus {
+    private listeners;
+    on<T = unknown>(event: string, callback: EventCallback<T>): () => void;
+    emit<T = unknown>(event: string, data: T): void;
+    once<T = unknown>(event: string, callback: EventCallback<T>): () => void;
+    removeAllListeners(event?: string): void;
+    listenerCount(event: string): number;
+}
+
+declare function downloadModel(options: ModelDownloadOptions): Promise<ModelDownloadResult>;
+
+declare class PythonEnvManager implements IPythonEnvironment {
+    private readonly dataDir;
+    private venvPath;
+    private cachedProbe;
+    constructor(dataDir: string);
+    probe(): Promise<PythonProbeResult>;
+    ensure(options: {
+        packages: readonly string[];
+    }): Promise<PythonEnvReady>;
+    spawn(script: string, args: readonly string[]): ChildProcess;
+}
+
+interface AddonInstallerConfig {
+    /** Directory where addons are installed (e.g., ~/.camstack/addons or {dataDir}/addons) */
+    readonly addonsDir: string;
+    /** Builtin packages to auto-install on first boot */
+    readonly builtinPackages: readonly string[];
+    /** npm registry URL (default: https://registry.npmjs.org) */
+    readonly registry?: string;
+}
+interface InstalledPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly path: string;
+}
+declare class AddonInstaller {
+    private readonly config;
+    constructor(config: AddonInstallerConfig);
+    /** Initialize addon directory — create if not exists, install builtins if needed */
+    initialize(): Promise<void>;
+    /** Ensure addon directory exists with a package.json */
+    private ensureAddonDirectory;
+    /** Install builtin packages if not already present */
+    private installBuiltins;
+    /** Check if a package is installed */
+    isInstalled(packageName: string): boolean;
+    /** Get installed package info */
+    getInstalledPackage(packageName: string): InstalledPackage | null;
+    /** List all installed addon packages (those with camstack.addons in package.json) */
+    listInstalled(): InstalledPackage[];
+    /** Install one or more packages from npm */
+    installPackages(packages: readonly string[]): Promise<void>;
+    /** Uninstall a package */
+    uninstallPackage(packageName: string): Promise<void>;
+    /** Update a package to latest version */
+    updatePackage(packageName: string): Promise<void>;
+    /** Update all packages */
+    updateAll(): Promise<void>;
+    /** Get the node_modules path for require/import resolution */
+    getNodeModulesPath(): string;
+}
+/** Default builtin packages that are auto-installed */
+declare const BUILTIN_PACKAGES: readonly string[];
+
+interface RegisteredAddon {
+    readonly declaration: AddonDeclaration;
+    readonly packageName: string;
+    readonly addonClass: new () => ICamstackAddon;
+}
+declare class AddonLoader {
+    private addons;
+    /** Load all addons from an npm package */
+    loadPackage(packageName: string): Promise<void>;
+    /** Load addon from a direct path (for development/testing) */
+    loadFromPath(addonId: string, modulePath: string, packageName: string): Promise<void>;
+    /** Get a registered addon by ID */
+    getAddon(addonId: string): RegisteredAddon | undefined;
+    /** List all registered addons */
+    listAddons(): RegisteredAddon[];
+    /** Check if an addon is registered */
+    hasAddon(addonId: string): boolean;
+    /** Create a new instance of an addon (not yet initialized) */
+    createInstance(addonId: string): ICamstackAddon;
+    /** Load all installed addon packages from the addon directory */
+    loadAllInstalled(installer: AddonInstaller): Promise<void>;
+    /** Load addon package from a specific filesystem path */
+    loadPackageFromPath(packageName: string, packagePath: string): Promise<void>;
+}
+
+declare class AddonEngineManager {
+    private readonly loader;
+    private readonly baseContext;
+    private engines;
+    constructor(loader: AddonLoader, baseContext: Omit<AddonContext, 'addonConfig'>);
+    /**
+     * Get or create an addon engine for the given effective config.
+     * Cameras with the same addonId + effective config share the same engine.
+     */
+    getOrCreateEngine(addonId: string, globalConfig: Record<string, unknown>, cameraOverride?: Record<string, unknown>): Promise<ICamstackAddon>;
+    /** Get all active engines */
+    getActiveEngines(): Map<string, ICamstackAddon>;
+    /** Shutdown a specific engine by its config key */
+    shutdownEngine(configKey: string): Promise<void>;
+    /** Shutdown all engines */
+    shutdownAll(): Promise<void>;
+    /** Compute a deterministic config key (visible for tests) */
+    computeConfigKey(addonId: string, effectiveConfig: Record<string, unknown>): string;
+    private hashConfig;
+}
+
+interface ValidationIssue {
+    readonly step?: string;
+    readonly addon?: string;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+}
+interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationIssue[];
+    readonly warnings: readonly ValidationIssue[];
+}
+declare class PipelineValidator {
+    private readonly loader;
+    constructor(loader: AddonLoader);
+    validate(config: PipelineConfig): ValidationResult;
+    private validateNode;
+}
+
+declare class PipelineRunner {
+    private readonly engineManager;
+    private readonly addonConfigs;
+    constructor(engineManager: AddonEngineManager, addonConfigs: Map<string, Record<string, unknown>>);
+    run(frame: FrameInput, config: PipelineConfig): Promise<PipelineResult>;
+    private executeNode;
+    private executeChildren;
+}
+
+export { AddonEngineManager, AddonInstaller, type AddonInstallerConfig, AddonLoader, BUILTIN_PACKAGES, EventBus, type InstalledPackage, PipelineRunner, PipelineValidator, PythonEnvManager, type RegisteredAddon, type ValidationIssue, type ValidationResult, downloadModel };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import { ModelDownloadOptions, ModelDownloadResult, IPythonEnvironment, PythonProbeResult, PythonEnvReady, AddonDeclaration, ICamstackAddon, AddonContext, PipelineConfig, FrameInput, PipelineResult } from '@camstack/types';
+import { ChildProcess } from 'node:child_process';
+
+type EventCallback<T = unknown> = (data: T) => void;
+declare class EventBus {
+    private listeners;
+    on<T = unknown>(event: string, callback: EventCallback<T>): () => void;
+    emit<T = unknown>(event: string, data: T): void;
+    once<T = unknown>(event: string, callback: EventCallback<T>): () => void;
+    removeAllListeners(event?: string): void;
+    listenerCount(event: string): number;
+}
+
+declare function downloadModel(options: ModelDownloadOptions): Promise<ModelDownloadResult>;
+
+declare class PythonEnvManager implements IPythonEnvironment {
+    private readonly dataDir;
+    private venvPath;
+    private cachedProbe;
+    constructor(dataDir: string);
+    probe(): Promise<PythonProbeResult>;
+    ensure(options: {
+        packages: readonly string[];
+    }): Promise<PythonEnvReady>;
+    spawn(script: string, args: readonly string[]): ChildProcess;
+}
+
+interface AddonInstallerConfig {
+    /** Directory where addons are installed (e.g., ~/.camstack/addons or {dataDir}/addons) */
+    readonly addonsDir: string;
+    /** Builtin packages to auto-install on first boot */
+    readonly builtinPackages: readonly string[];
+    /** npm registry URL (default: https://registry.npmjs.org) */
+    readonly registry?: string;
+}
+interface InstalledPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly path: string;
+}
+declare class AddonInstaller {
+    private readonly config;
+    constructor(config: AddonInstallerConfig);
+    /** Initialize addon directory — create if not exists, install builtins if needed */
+    initialize(): Promise<void>;
+    /** Ensure addon directory exists with a package.json */
+    private ensureAddonDirectory;
+    /** Install builtin packages if not already present */
+    private installBuiltins;
+    /** Check if a package is installed */
+    isInstalled(packageName: string): boolean;
+    /** Get installed package info */
+    getInstalledPackage(packageName: string): InstalledPackage | null;
+    /** List all installed addon packages (those with camstack.addons in package.json) */
+    listInstalled(): InstalledPackage[];
+    /** Install one or more packages from npm */
+    installPackages(packages: readonly string[]): Promise<void>;
+    /** Uninstall a package */
+    uninstallPackage(packageName: string): Promise<void>;
+    /** Update a package to latest version */
+    updatePackage(packageName: string): Promise<void>;
+    /** Update all packages */
+    updateAll(): Promise<void>;
+    /** Get the node_modules path for require/import resolution */
+    getNodeModulesPath(): string;
+}
+/** Default builtin packages that are auto-installed */
+declare const BUILTIN_PACKAGES: readonly string[];
+
+interface RegisteredAddon {
+    readonly declaration: AddonDeclaration;
+    readonly packageName: string;
+    readonly addonClass: new () => ICamstackAddon;
+}
+declare class AddonLoader {
+    private addons;
+    /** Load all addons from an npm package */
+    loadPackage(packageName: string): Promise<void>;
+    /** Load addon from a direct path (for development/testing) */
+    loadFromPath(addonId: string, modulePath: string, packageName: string): Promise<void>;
+    /** Get a registered addon by ID */
+    getAddon(addonId: string): RegisteredAddon | undefined;
+    /** List all registered addons */
+    listAddons(): RegisteredAddon[];
+    /** Check if an addon is registered */
+    hasAddon(addonId: string): boolean;
+    /** Create a new instance of an addon (not yet initialized) */
+    createInstance(addonId: string): ICamstackAddon;
+    /** Load all installed addon packages from the addon directory */
+    loadAllInstalled(installer: AddonInstaller): Promise<void>;
+    /** Load addon package from a specific filesystem path */
+    loadPackageFromPath(packageName: string, packagePath: string): Promise<void>;
+}
+
+declare class AddonEngineManager {
+    private readonly loader;
+    private readonly baseContext;
+    private engines;
+    constructor(loader: AddonLoader, baseContext: Omit<AddonContext, 'addonConfig'>);
+    /**
+     * Get or create an addon engine for the given effective config.
+     * Cameras with the same addonId + effective config share the same engine.
+     */
+    getOrCreateEngine(addonId: string, globalConfig: Record<string, unknown>, cameraOverride?: Record<string, unknown>): Promise<ICamstackAddon>;
+    /** Get all active engines */
+    getActiveEngines(): Map<string, ICamstackAddon>;
+    /** Shutdown a specific engine by its config key */
+    shutdownEngine(configKey: string): Promise<void>;
+    /** Shutdown all engines */
+    shutdownAll(): Promise<void>;
+    /** Compute a deterministic config key (visible for tests) */
+    computeConfigKey(addonId: string, effectiveConfig: Record<string, unknown>): string;
+    private hashConfig;
+}
+
+interface ValidationIssue {
+    readonly step?: string;
+    readonly addon?: string;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+}
+interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationIssue[];
+    readonly warnings: readonly ValidationIssue[];
+}
+declare class PipelineValidator {
+    private readonly loader;
+    constructor(loader: AddonLoader);
+    validate(config: PipelineConfig): ValidationResult;
+    private validateNode;
+}
+
+declare class PipelineRunner {
+    private readonly engineManager;
+    private readonly addonConfigs;
+    constructor(engineManager: AddonEngineManager, addonConfigs: Map<string, Record<string, unknown>>);
+    run(frame: FrameInput, config: PipelineConfig): Promise<PipelineResult>;
+    private executeNode;
+    private executeChildren;
+}
+
+export { AddonEngineManager, AddonInstaller, type AddonInstallerConfig, AddonLoader, BUILTIN_PACKAGES, EventBus, type InstalledPackage, PipelineRunner, PipelineValidator, PythonEnvManager, type RegisteredAddon, type ValidationIssue, type ValidationResult, downloadModel };