@pellux/goodvibes-tui 0.18.10 → 0.18.12

package/src/runtime/plugins/manager.ts

@@ -1,474 +0,0 @@
-/**
- * PluginLifecycleManager — plugin lifecycle and capability enforcement.
- *
- * Tracks all plugins through the 8-state lifecycle machine, resolves capability
- * manifests on load, and emits PluginEvents at every state transition.
- *
- * Gated by the `plugin-lifecycle` feature flag.
- */
-
-import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
-import type { PluginEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/plugins';
-import { RuntimeEventBus } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
-import type { RuntimeEventBus as RuntimeEventBusContract } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
-import type { PluginLoaderDeps, LoadedPlugin } from '../../plugins/loader';
-import {
-  discoverPlugins,
-  loadPlugin,
-  unloadPlugin,
-  type PluginPathOptions,
-} from '../../plugins/loader';
-import type { PluginLifecycleState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/plugins';
-import {
-  type PluginCapability,
-  type PluginLifecycleManagerOptions,
-  type PluginLifecycleRecord,
-  type PluginManifestV2,
-  type PluginTransition,
-  MAX_TRANSITION_HISTORY,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-import { applyTransition, isOperational } from '@pellux/goodvibes-sdk/platform/runtime/plugins/lifecycle';
-import { resolveCapabilityManifest } from '@pellux/goodvibes-sdk/platform/runtime/plugins/manifest';
-import { PluginTrustStore, type PluginTrustTier } from '@pellux/goodvibes-sdk/platform/runtime/plugins/trust';
-import { PluginQuarantineEngine } from '@pellux/goodvibes-sdk/platform/runtime/plugins/quarantine';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
-import {
-  emitPluginActive,
-  emitPluginDegraded,
-  emitPluginDisabled,
-  emitPluginDiscovered,
-  emitPluginError,
-  emitPluginLoaded,
-  emitPluginLoading,
-  emitPluginUnloading,
-} from '@pellux/goodvibes-sdk/platform/runtime/emitters/plugins';
-
-/** Source label for emitted events. */
-const EVENT_SOURCE = 'plugin-lifecycle-manager';
-
-/**
- * PluginLifecycleManager tracks all plugins through structured lifecycle
- * transitions and emits typed PluginEvents at each state change.
- */
-export class PluginLifecycleManager {
-  private readonly records = new Map<string, PluginLifecycleRecord>();
-  private readonly sessionId: string;
-  private readonly capabilityPolicy: (name: string, cap: PluginCapability) => boolean;
-  private readonly trustTierResolver: (pluginName: string) => PluginTrustTier;
-  private readonly runtimeBus: RuntimeEventBusContract;
-
-  /** Trust store — manages tier records for all plugins. */
-  readonly trustStore: PluginTrustStore = new PluginTrustStore();
-  /** Quarantine engine — tracks and applies quarantine constraints. */
-  readonly quarantine: PluginQuarantineEngine = new PluginQuarantineEngine();
-
-  constructor(options: PluginLifecycleManagerOptions = {}) {
-    this.sessionId = options.sessionId ?? '';
-    this.capabilityPolicy = options.capabilityPolicy ?? (() => true);
-    this.trustTierResolver = options.trustTierResolver ?? ((name) => this.trustStore.getTier(name));
-    this.runtimeBus = options.runtimeBus ?? new RuntimeEventBus();
-  }
-
-  // ── Plugin record accessors ────────────────────────────────────────────────
-
-  /** Returns the lifecycle record for a plugin, or undefined if unknown. */
-  getRecord(name: string): Readonly<PluginLifecycleRecord> | undefined {
-    return this.records.get(name);
-  }
-
-  /** Returns all plugin lifecycle records as an array. */
-  getAllRecords(): ReadonlyArray<Readonly<PluginLifecycleRecord>> {
-    return Array.from(this.records.values());
-  }
-
-  /** Returns names of all plugins in a given state. */
-  getPluginsInState(state: PluginLifecycleState): string[] {
-    const result: string[] = [];
-    for (const [name, record] of this.records) {
-      if (record.state === state) result.push(name);
-    }
-    return result;
-  }
-
-  /** Returns names of all currently operational plugins (active or degraded). */
-  getOperationalPlugins(): string[] {
-    const result: string[] = [];
-    for (const [name, record] of this.records) {
-      if (isOperational(record.state)) result.push(name);
-    }
-    return result;
-  }
-
-  // ── Lifecycle operations ──────────────────────────────────────────────────
-
-  /**
-   * Register a discovered plugin. Creates its lifecycle record in the
-   * `discovered` state and emits PLUGIN_DISCOVERED.
-   */
-  registerDiscovered(manifest: PluginManifestV2, pluginDir: string): void {
-    const name = manifest.name;
-    if (this.records.has(name)) {
-      logger.debug(`[plugin-lifecycle] ${name}: already registered, skipping re-registration`);
-      return;
-    }
-
-    const tier = this.trustTierResolver(name);
-    const capabilities = resolveCapabilityManifest(name, manifest, this.capabilityPolicy, tier);
-
-    const record: PluginLifecycleRecord = {
-      name,
-      version: manifest.version,
-      state: 'discovered',
-      capabilities,
-      transitions: [],
-      reloading: false,
-      trustTier: tier,
-      quarantined: this.quarantine.isQuarantined(name),
-    };
-
-    this.records.set(name, record);
-
-    this.emit({
-      type: 'PLUGIN_DISCOVERED',
-      pluginId: name,
-      path: pluginDir,
-      version: manifest.version,
-    });
-
-    logger.debug(`[plugin-lifecycle] ${name}@${manifest.version}: registered (discovered)`);
-  }
-
-  /**
-   * Load a plugin using the existing loader infrastructure.
-   *
-   * Transitions: discovered/disabled → loading → loaded → active
-   * On failure:  loading → error
-   */
-  async loadPlugin(
-    manifest: PluginManifestV2,
-    pluginDir: string,
-    deps: PluginLoaderDeps,
-    cacheBust?: number,
-  ): Promise<boolean> {
-    const name = manifest.name;
-    let record = this.records.get(name);
-
-    if (!record) {
-      this.registerDiscovered(manifest, pluginDir);
-      record = this.records.get(name)!;
-    }
-
-    // discovered → loading (or disabled → loading for re-enable)
-    const toLoadingResult = this.transition(name, 'loading');
-    if (!toLoadingResult.ok) {
-      logger.warn(`[plugin-lifecycle] ${name}: cannot start load — ${toLoadingResult.reason}`);
-      return false;
-    }
-
-    this.emit({ type: 'PLUGIN_LOADING', pluginId: name, path: pluginDir });
-
-    try {
-      const loaded = await loadPlugin({ manifest, pluginDir }, deps, cacheBust);
-
-      if (!loaded) {
-        this.transition(name, 'error', 'loadPlugin returned null');
-        this.updateRecord(name, { lastError: 'loadPlugin returned null', errorAt: Date.now() });
-        this.emit({
-          type: 'PLUGIN_ERROR',
-          pluginId: name,
-          error: 'loadPlugin returned null',
-          fatal: false,
-        });
-        return false;
-      }
-
-      // loading → loaded
-      this.transition(name, 'loaded');
-
-      // loaded → active
-      const toActiveResult = this.transition(name, 'active');
-      if (!toActiveResult.ok) {
-        logger.warn(`[plugin-lifecycle] ${name}: cannot transition to active — ${toActiveResult.reason}`);
-        return false;
-      }
-
-      this.updateRecord(name, { activatedAt: Date.now() });
-
-      this.emit({
-        type: 'PLUGIN_LOADED',
-        pluginId: name,
-        version: manifest.version,
-        capabilities: record.capabilities.granted as string[],
-      });
-      this.emit({ type: 'PLUGIN_ACTIVE', pluginId: name });
-
-      logger.info(`[plugin-lifecycle] ${name}@${manifest.version}: active`);
-      return true;
-    } catch (err) {
-      const errorMsg = summarizeError(err);
-      this.transition(name, 'error', errorMsg);
-      this.updateRecord(name, { lastError: errorMsg, errorAt: Date.now() });
-      this.emit({
-        type: 'PLUGIN_ERROR',
-        pluginId: name,
-        error: errorMsg,
-        fatal: false,
-      });
-      logger.error(`[plugin-lifecycle] ${name}: load threw — ${errorMsg}`);
-      return false;
-    }
-  }
-
-  /**
-   * Unload a plugin. Transitions active/loaded/degraded → unloading → disabled.
-   */
-  async unloadPlugin(
-    name: string,
-    reason?: string,
-    loaderDeps?: { getLoadedPlugin?: (name: string) => LoadedPlugin | undefined },
-  ): Promise<void> {
-    const record = this.records.get(name);
-    if (!record) {
-      logger.debug(`[plugin-lifecycle] ${name}: unload requested but not tracked`);
-      return;
-    }
-
-    const toUnloadingResult = this.transition(name, 'unloading', reason);
-    if (!toUnloadingResult.ok) {
-      logger.warn(`[plugin-lifecycle] ${name}: cannot unload — ${toUnloadingResult.reason}`);
-      return;
-    }
-
-    this.emit({ type: 'PLUGIN_UNLOADING', pluginId: name, reason });
-
-    // Delegate to the existing unloadPlugin function if a loaded instance is available.
-    const loadedPlugin = loaderDeps?.getLoadedPlugin?.(name);
-    if (loadedPlugin) {
-      await unloadPlugin(loadedPlugin);
-    }
-
-    this.transition(name, 'disabled', reason);
-    this.emit({
-      type: 'PLUGIN_DISABLED',
-      pluginId: name,
-      reason: reason ?? 'unloaded',
-    });
-
-    logger.info(`[plugin-lifecycle] ${name}: disabled${reason ? ` (${reason})` : ''}`);
-  }
-
-  // ── Trust & Quarantine operations ────────────────────────────────────────
-
-  /**
-   * setTrustTier — Assign a trust tier to a plugin and re-sync the record.
-   *
-   * If the plugin has an active lifecycle record, the trust tier in the record
-   * is updated immediately. Capability re-resolution requires a reload.
-   */
-  setTrustTier(name: string, tier: PluginTrustTier, note?: string): void {
-    this.trustStore.setTier(name, tier, { note });
-    const record = this.records.get(name);
-    if (record) {
-      record.trustTier = tier;
-    }
-    logger.info(`[plugin-lifecycle] ${name}: trust tier set to '${tier}'${note ? ` — ${note}` : ''}`);
-  }
-
-  /**
-   * quarantinePlugin — Apply quarantine to a named plugin.
-   *
-   * Revokes high-risk capabilities from the live manifest and marks the record
-   * as quarantined. Emits PLUGIN_DEGRADED to signal partial functionality.
-   *
-   * @returns true if quarantine was applied; false if not tracked or already quarantined.
-   */
-  quarantinePlugin(name: string, reason: string): boolean {
-    const record = this.records.get(name);
-    if (!record) {
-      logger.warn(`[plugin-lifecycle] ${name}: quarantine requested but plugin not tracked`);
-      return false;
-    }
-
-    const qRecord = this.quarantine.quarantine(name, record.capabilities, reason);
-    if (!qRecord) return false;
-
-    record.quarantined = true;
-
-    this.emit({
-      type: 'PLUGIN_DEGRADED',
-      pluginId: name,
-      reason: `quarantined: ${reason}`,
-      affectedCapabilities: qRecord.revokedCapabilities as string[],
-    });
-
-    return true;
-  }
-
-  /**
-   * liftQuarantine — Remove quarantine from a plugin.
-   *
-   * Capabilities are NOT restored here; the operator should reload the plugin
-   * after lifting so that trust-aware re-resolution can grant capabilities
-   * appropriate for the updated tier.
-   *
-   * @returns true if quarantine was lifted; false if no active quarantine.
-   */
-  liftQuarantine(name: string): boolean {
-    const lifted = this.quarantine.lift(name);
-    const record = this.records.get(name);
-    if (record) {
-      record.quarantined = false;
-    }
-    if (lifted) {
-      logger.info(`[plugin-lifecycle] ${name}: quarantine lifted — reload to restore capabilities`);
-    }
-    return lifted;
-  }
-
-  /**
-   * Mark a plugin as degraded (partial functionality). Only valid from active.
-   */
-  degradePlugin(name: string, reason: string, affectedCapabilities: string[] = []): void {
-    const record = this.records.get(name);
-    if (!record) return;
-
-    const result = this.transition(name, 'degraded', reason);
-    if (!result.ok) {
-      logger.warn(`[plugin-lifecycle] ${name}: cannot degrade — ${result.reason}`);
-      return;
-    }
-
-    this.emit({
-      type: 'PLUGIN_DEGRADED',
-      pluginId: name,
-      reason,
-      affectedCapabilities,
-    });
-
-    logger.warn(`[plugin-lifecycle] ${name}: degraded — ${reason}`);
-  }
-
-  /**
-   * Record a non-fatal error without transitioning state.
-   * If the plugin is active, it may optionally be moved to degraded.
-   */
-  recordError(name: string, error: string, fatal: boolean): void {
-    const record = this.records.get(name);
-    if (!record) return;
-
-    this.updateRecord(name, { lastError: error, errorAt: Date.now() });
-    this.emit({ type: 'PLUGIN_ERROR', pluginId: name, error, fatal });
-
-    if (fatal && (record.state === 'active' || record.state === 'loaded' || record.state === 'degraded')) {
-      this.transition(name, 'error', error);
-    }
-
-    logger.error(`[plugin-lifecycle] ${name}: error (fatal=${String(fatal)}) — ${error}`);
-  }
-
-  // ── Bulk operations ───────────────────────────────────────────────────────
-
-  /**
-   * Scan for plugins and register newly discovered ones.
-   * Existing records are not modified.
-   */
-  scanAndRegister(pathOptions: PluginPathOptions): void {
-    const discovered = discoverPlugins(pathOptions);
-    for (const { manifest, pluginDir } of discovered) {
-      if (!this.records.has(manifest.name)) {
-        this.registerDiscovered(manifest as PluginManifestV2, pluginDir);
-      }
-    }
-    logger.debug(`[plugin-lifecycle] Scan complete: ${discovered.length} plugin(s) found`);
-  }
-
-  // ── Private helpers ───────────────────────────────────────────────────────
-
-  /**
-   * Apply a state machine transition for a named plugin.
-   * Records the transition in the plugin's history.
-   * Returns the TransitionResult from the state machine.
-   */
-  private transition(
-    name: string,
-    to: PluginLifecycleState,
-    reason?: string,
-  ): { ok: boolean; reason?: string } {
-    const record = this.records.get(name);
-    if (!record) return { ok: false, reason: `Plugin '${name}' not tracked` };
-
-    const result = applyTransition(record.state, to);
-    if (!result.ok) return result;
-
-    const entry: PluginTransition = {
-      pluginName: name,
-      from: result.from,
-      to: result.to,
-      ts: Date.now(),
-      reason,
-    };
-
-    // Mutate the record in place — the record lives inside the Map.
-    record.transitions.push(entry);
-    if (record.transitions.length > MAX_TRANSITION_HISTORY) {
-      record.transitions.shift();
-    }
-    record.state = to;
-
-    logger.debug(`[plugin-lifecycle] ${name}: ${result.from} → ${to}${reason ? ` (${reason})` : ''}`);
-    return { ok: true };
-  }
-
-  /**
-   * Partially update a plugin record's mutable fields.
-   */
-  private updateRecord(
-    name: string,
-    patch: Partial<Pick<PluginLifecycleRecord, 'lastError' | 'errorAt' | 'activatedAt' | 'reloading' | 'trustTier' | 'quarantined'>>,
-  ): void {
-    const record = this.records.get(name);
-    if (!record) return;
-    if (patch.lastError !== undefined) record.lastError = patch.lastError;
-    if (patch.errorAt !== undefined) record.errorAt = patch.errorAt;
-    if (patch.activatedAt !== undefined) record.activatedAt = patch.activatedAt;
-    if (patch.reloading !== undefined) record.reloading = patch.reloading;
-  }
-
-  private emit(event: PluginEvent): void {
-    const ctx = {
-      sessionId: this.sessionId,
-      traceId: `plugin-lifecycle:${event.pluginId}`,
-      source: EVENT_SOURCE,
-    } as const;
-    try {
-      switch (event.type) {
-        case 'PLUGIN_DISCOVERED':
-          emitPluginDiscovered(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_LOADING':
-          emitPluginLoading(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_LOADED':
-          emitPluginLoaded(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_ACTIVE':
-          emitPluginActive(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_DEGRADED':
-          emitPluginDegraded(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_ERROR':
-          emitPluginError(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_UNLOADING':
-          emitPluginUnloading(this.runtimeBus, ctx, event);
-          break;
-        case 'PLUGIN_DISABLED':
-          emitPluginDisabled(this.runtimeBus, ctx, event);
-          break;
-      }
-    } catch (err) {
-      logger.debug(`[plugin-lifecycle] runtime emit failed: ${summarizeError(err)}`);
-    }
-  }
-}

package/src/runtime/plugins/manifest.ts

@@ -1,167 +0,0 @@
-/**
- * Plugin capability manifest validation and resolution.
- *
- * Implements deny-by-default capability enforcement:
- * 1. Parse raw manifest capabilities (unknown → typed)
- * 2. Validate that each requested capability is a known capability
- * 3. Run the runtime's capability policy to grant or deny each capability
- * 4. Return a resolved PluginCapabilityManifest
- */
-
-import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
-import {
-  ALL_CAPABILITIES,
-  HIGH_RISK_CAPABILITIES,
-  type PluginCapability,
-  type PluginCapabilityManifest,
-  type PluginManifestV2,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-import { type PluginTrustTier, filterCapabilitiesByTrust } from '@pellux/goodvibes-sdk/platform/runtime/plugins/trust';
-
-/**
- * Default capability policy: grant all valid capabilities.
- *
- * Callers can supply a stricter policy via PluginLifecycleManagerOptions.
- */
-function defaultPolicy(_pluginName: string, _capability: PluginCapability): boolean {
-  return true;
-}
-
-/**
- * Returns whether a string value is a known PluginCapability.
- */
-function isKnownCapability(value: string): value is PluginCapability {
-  return (ALL_CAPABILITIES as ReadonlyArray<string>).includes(value);
-}
-
-/**
- * resolveCapabilityManifest — Parse and resolve the capability manifest for a
- * plugin, applying the runtime's capability policy and trust-tier constraints.
- *
- * Evaluation order:
- *   1. Unknown capability strings are filtered out (warn + ignore).
- *   2. Trust-tier constraints are applied — high-risk capabilities blocked
- *      unless the plugin has the `trusted` tier.
- *   3. The runtime capability policy callback is applied to the remaining set.
- *
- * @param pluginName - Plugin name (for logging).
- * @param manifest   - The raw plugin manifest (may have `capabilities` array).
- * @param policy     - Capability grant/deny callback. Defaults to permissive.
- * @param trustTier  - Effective trust tier for this plugin. Defaults to 'untrusted'.
- * @returns A fully-resolved PluginCapabilityManifest.
- */
-export function resolveCapabilityManifest(
-  pluginName: string,
-  manifest: PluginManifestV2,
-  policy: (name: string, cap: PluginCapability) => boolean = defaultPolicy,
-  trustTier: PluginTrustTier = 'untrusted',
-): PluginCapabilityManifest {
-  const rawRequested = manifest.capabilities ?? [];
-
-  // Validate and filter unknown capability strings.
-  const requested: PluginCapability[] = [];
-  for (const raw of rawRequested) {
-    if (isKnownCapability(raw)) {
-      requested.push(raw);
-    } else {
-      logger.warn(
-        `[plugin-lifecycle:${pluginName}] Unknown capability '${raw}' — ignored`,
-      );
-    }
-  }
-
-  // Apply trust-tier constraints before the policy callback.
-  const trustResult = filterCapabilitiesByTrust(requested, trustTier);
-  if (trustResult.blocked.length > 0) {
-    logger.warn(
-      `[plugin-lifecycle:${pluginName}] Trust tier '${trustTier}' blocks` +
-      ` high-risk capabilities: [${trustResult.blocked.join(', ')}]` +
-      ' — trust escalation required',
-    );
-  }
-
-  // Only the trust-permitted capabilities proceed to policy evaluation.
-  const afterTrust = trustResult.permitted;
-
-  const granted: PluginCapability[] = [];
-  const denied: PluginCapability[] = [...trustResult.blocked];
-  const denialReasons: Partial<Record<PluginCapability, string>> = { ...trustResult.reasons };
-
-  for (const cap of afterTrust) {
-    if (policy(pluginName, cap)) {
-      granted.push(cap);
-    } else {
-      denied.push(cap);
-      denialReasons[cap] = `Capability '${cap}' denied by runtime policy`;
-      logger.warn(
-        `[plugin-lifecycle:${pluginName}] Capability '${cap}' denied by policy`,
-      );
-    }
-  }
-
-  logger.debug(
-    `[plugin-lifecycle:${pluginName}] Capabilities resolved (trust=${trustTier})` +
-    ` — granted: [${granted.join(', ')}]` +
-    (denied.length > 0 ? `, denied: [${denied.join(', ')}]` : ''),
-  );
-
-  return {
-    requested: Object.freeze(requested),
-    granted,
-    denied,
-    denialReasons,
-  };
-}
-
-/**
- * isHighRiskCapability — Returns whether a capability is classified as high-risk.
- * High-risk capabilities require the `trusted` tier to be granted.
- */
-export function isHighRiskCapability(capability: PluginCapability): boolean {
-  return (HIGH_RISK_CAPABILITIES as ReadonlyArray<string>).includes(capability);
-}
-
-/**
- * hasCapability — Returns whether a plugin has been granted a specific
- * capability after manifest resolution.
- */
-export function hasCapability(
-  manifest: PluginCapabilityManifest,
-  capability: PluginCapability,
-): boolean {
-  return manifest.granted.includes(capability);
-}
-
-/**
- * validateManifestV2 — Light validation of the PluginManifestV2 shape.
- * Returns null on success or an error string on failure.
- */
-export function validateManifestV2(manifest: unknown): string | null {
-  if (!manifest || typeof manifest !== 'object') {
-    return 'manifest must be an object';
-  }
-  const m = manifest as Record<string, unknown>;
-  if (typeof m['name'] !== 'string' || !m['name']) {
-    return "manifest.name must be a non-empty string";
-  }
-  if (typeof m['version'] !== 'string' || !m['version']) {
-    return "manifest.version must be a non-empty string";
-  }
-  if (typeof m['description'] !== 'string') {
-    return "manifest.description must be a string";
-  }
-  if (m['capabilities'] !== undefined) {
-    if (!Array.isArray(m['capabilities'])) {
-      return "manifest.capabilities must be an array";
-    }
-    for (const cap of m['capabilities'] as unknown[]) {
-      if (typeof cap !== 'string') {
-        return `manifest.capabilities entries must be strings, got: ${typeof cap}`;
-      }
-    }
-  }
-  if (m['minRuntimeVersion'] !== undefined && typeof m['minRuntimeVersion'] !== 'string') {
-    return "manifest.minRuntimeVersion must be a string";
-  }
-  return null;
-}