@pellux/goodvibes-tui 0.18.10 → 0.18.12

package/src/runtime/permissions/rule-suggestions.ts

@@ -1,36 +0,0 @@
-import type { PermissionAuditEntry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-runtime';
-
-export interface PermissionRuleSuggestion {
-  readonly id: string;
-  readonly tool: string;
-  readonly command: string;
-  readonly summary: string;
-  readonly reason: string;
-}
-
-export function buildPermissionRuleSuggestions(
-  audit: readonly PermissionAuditEntry[],
-): PermissionRuleSuggestion[] {
-  const denied = audit.filter((entry) => entry.approved === false);
-  const grouped = new Map<string, PermissionAuditEntry[]>();
-  for (const entry of denied) {
-    const key = `${entry.tool}:${entry.target ?? entry.host ?? entry.summary}`;
-    const list = grouped.get(key) ?? [];
-    list.push(entry);
-    grouped.set(key, list);
-  }
-  return [...grouped.entries()]
-    .filter(([, entries]) => entries.length >= 2)
-    .map(([key, entries]) => {
-      const sample = entries[0]!;
-      const target = sample.target ?? sample.host ?? sample.summary;
-      return {
-        id: key,
-        tool: sample.tool,
-        command: `/policy simulate ${sample.tool}${target ? ` --target ${JSON.stringify(target)}` : ''}`,
-        summary: `Repeated denials for ${sample.tool}`,
-        reason: `${entries.length} denials suggest a durable scoped rule or policy review may be appropriate.`,
-      } satisfies PermissionRuleSuggestion;
-    })
-    .sort((a, b) => a.tool.localeCompare(b.tool));
-}

package/src/runtime/plugins/hot-reload.ts

@@ -1,221 +0,0 @@
-/**
- * Safe hot-reload protocol for plugins.
- *
- * Implements the 6-phase hot-reload sequence:
- *   1. Quiesce   — stop accepting new work from the plugin
- *   2. Unregister — remove plugin's registrations (commands, tools, hooks)
- *   3. Unload    — deactivate and clean up the old plugin instance
- *   4. Reload    — load the new version with a cache-bust timestamp
- *   5. Re-register — new instance calls init/activate (registers naturally)
- *   6. Health check → active (healthy) or degraded (unhealthy)
- */
-
-import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
-import type { PluginLoaderDeps } from '../../plugins/loader';
-import type { LoadedPlugin } from '../../plugins/loader';
-import type { PluginHealthCheckResult, PluginManifestV2 } from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-import type { PluginLifecycleManager } from '@pellux/goodvibes-sdk/platform/runtime/plugins/manager';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
-
-/**
- * Options for a single plugin hot-reload operation.
- */
-export interface HotReloadOptions {
-  /**
-   * Callback to retrieve the current loaded plugin instance by name.
-   * Used to call deactivate() and run cleanup before unloading.
-   */
-  getLoadedPlugin: (name: string) => LoadedPlugin | undefined;
-
-  /**
-   * Callback to remove a plugin's loaded instance from the host's registry.
-   * Called after unload to clean up the host-side reference.
-   */
-  removeLoadedPlugin: (name: string) => void;
-
-  /**
-   * Callback to store the newly loaded plugin instance in the host's registry.
-   * Called after a successful reload.
-   */
-  storeLoadedPlugin: (name: string, plugin: LoadedPlugin) => void;
-
-  /**
-   * Optional health check callback invoked after re-registration.
-   * Return a PluginHealthCheckResult to indicate whether the plugin is healthy.
-   * Defaults to a trivial healthy check.
-   */
-  healthCheck?: (name: string) => Promise<PluginHealthCheckResult>;
-
-  /**
-   * Maximum time (ms) to wait for the health check before timing out.
-   * Defaults to 5000ms.
-   */
-  healthCheckTimeoutMs?: number;
-}
-
-/**
- * Result of a hot-reload operation.
- */
-export interface HotReloadResult {
-  /** Whether the reload completed successfully and the plugin is healthy. */
-  success: boolean;
-  /** Phase that failed (if success === false). */
-  failedPhase?: 'quiesce' | 'unregister' | 'unload' | 'reload' | 're-register' | 'health-check';
-  /** Error message (if success === false). */
-  error?: string;
-  /** Duration of the reload in milliseconds. */
-  durationMs: number;
-  /** Whether the plugin ended in degraded state (partial success). */
-  degraded: boolean;
-}
-
-/** Default trivial health check — always returns healthy. */
-async function defaultHealthCheck(name: string): Promise<PluginHealthCheckResult> {
-  return {
-    healthy: true,
-    message: `${name}: health check passed (default)`,
-    durationMs: 0,
-  };
-}
-
-/**
- * runHotReload — Execute the safe 6-phase hot-reload protocol for a single
- * plugin.
- *
- * @param name      - Plugin name.
- * @param manifest  - Current manifest for the plugin.
- * @param pluginDir - Absolute path to the plugin directory.
- * @param deps      - Loader dependencies (runtime bus, registries, etc.).
- * @param lcm       - PluginLifecycleManager to track state transitions.
- * @param options   - Host-side callbacks and configuration.
- * @returns HotReloadResult describing the outcome.
- */
-export async function runHotReload(
-  name: string,
-  manifest: PluginManifestV2,
-  pluginDir: string,
-  deps: PluginLoaderDeps,
-  lcm: PluginLifecycleManager,
-  options: HotReloadOptions,
-): Promise<HotReloadResult> {
-  const startTs = Date.now();
-  const healthCheck = options.healthCheck ?? defaultHealthCheck;
-  const timeoutMs = options.healthCheckTimeoutMs ?? 5000;
-
-  const record = lcm.getRecord(name);
-  if (!record) {
-    return {
-      success: false,
-      failedPhase: 'quiesce',
-      error: `Plugin '${name}' is not tracked by the lifecycle manager`,
-      durationMs: Date.now() - startTs,
-      degraded: false,
-    };
-  }
-
-  logger.info(`[plugin-hot-reload] ${name}: starting hot-reload`);
-
-  // ── Phase 1: Quiesce ────────────────────────────────────────────────────
-  // Mark the plugin as reloading to signal to callers to defer new work.
-  // (The PluginLifecycleRecord.reloading flag is set, but state is not changed.)
-  // In a future implementation this phase could drain in-flight requests.
-  try {
-    // Access via cast since reloading is a mutable field on the record.
-    const mutableRecord = record as { reloading: boolean };
-    mutableRecord.reloading = true;
-    logger.debug(`[plugin-hot-reload] ${name}: phase 1/6 quiesced`);
-  } catch (err) {
-    return failure('quiesce', summarizeError(err), startTs);
-  }
-
-  // ── Phase 2: Prepare unregister ──────────────────────────────────────────
-  // The existing plugin's cleanup callbacks handle un-registration during
-  // unload, so there is no separate hook dispatch here.
-  logger.debug(`[plugin-hot-reload] ${name}: phase 2/6 unregister scheduled with unload cleanup`);
-
-  // ── Phase 3: Unload ─────────────────────────────────────────────────────
-  try {
-    const loaded = options.getLoadedPlugin(name);
-    if (loaded) {
-      const { unloadPlugin } = await import('../../plugins/loader.ts');
-      await unloadPlugin(loaded);
-    }
-    options.removeLoadedPlugin(name);
-    logger.debug(`[plugin-hot-reload] ${name}: phase 3/6 unloaded`);
-  } catch (err) {
-    return failure('unload', summarizeError(err), startTs);
-  }
-
-  // ── Phase 4 + 5: Reload + Re-register ──────────────────────────────────
-  // loadPlugin calls init() and activate() which re-registers everything.
-  let reloadedPlugin: import('../../plugins/loader.ts').LoadedPlugin | null = null;
-  try {
-    const { loadPlugin } = await import('../../plugins/loader.ts');
-    const cacheBust = Date.now();
-    reloadedPlugin = await loadPlugin({ manifest, pluginDir }, deps, cacheBust);
-    if (!reloadedPlugin) {
-      return failure('reload', 'loadPlugin returned null', startTs);
-    }
-    options.storeLoadedPlugin(name, reloadedPlugin);
-    logger.debug(`[plugin-hot-reload] ${name}: phases 4+5/6 reloaded + re-registered`);
-  } catch (err) {
-    return failure('reload', summarizeError(err), startTs);
-  }
-
-  // ── Phase 6: Health check ────────────────────────────────────────────────
-  let healthResult: PluginHealthCheckResult;
-  try {
-    healthResult = await Promise.race([
-      healthCheck(name),
-      new Promise<PluginHealthCheckResult>((_, reject) =>
-        setTimeout(() => reject(new Error(`health check timed out after ${timeoutMs}ms`)), timeoutMs),
-      ),
-    ]);
-  } catch (err) {
-    healthResult = {
-      healthy: false,
-      message: summarizeError(err),
-      durationMs: Date.now() - startTs,
-    };
-  }
-
-  // Clear reloading flag.
-  try {
-    const mutableRecord = lcm.getRecord(name) as { reloading: boolean } | undefined;
-    if (mutableRecord) mutableRecord.reloading = false;
-  } catch { /* non-fatal */ }
-
-  if (healthResult.healthy) {
-    logger.info(`[plugin-hot-reload] ${name}: hot-reload complete — active (${Date.now() - startTs}ms)`);
-    return {
-      success: true,
-      durationMs: Date.now() - startTs,
-      degraded: false,
-    };
-  } else {
-    // Plugin loaded but health check failed → degraded.
-    lcm.degradePlugin(name, `Health check failed: ${healthResult.message}`);
-    logger.warn(`[plugin-hot-reload] ${name}: hot-reload complete — degraded (${healthResult.message})`);
-    return {
-      success: true, // reload succeeded; just in degraded state
-      durationMs: Date.now() - startTs,
-      degraded: true,
-    };
-  }
-}
-
-/** Build a failure result for a named phase. */
-function failure(
-  phase: HotReloadResult['failedPhase'],
-  error: string,
-  startTs: number,
-): HotReloadResult {
-  logger.error(`[plugin-hot-reload] phase '${String(phase)}' failed: ${error}`);
-  return {
-    success: false,
-    failedPhase: phase,
-    error,
-    durationMs: Date.now() - startTs,
-    degraded: false,
-  };
-}

package/src/runtime/plugins/index.ts

@@ -1,84 +0,0 @@
-/**
- * Plugin lifecycle system — barrel export and factory.
- *
- * Gated by the `plugin-lifecycle` feature flag. Import and call
- * `createPluginLifecycleManager()` at startup after the feature flag
- * manager has been initialised.
- *
- * @example
- * ```ts
- * import { createPluginLifecycleManager } from './src/runtime/plugins/index.ts';
- *
- * const lcm = createPluginLifecycleManager({ sessionId: session.id, runtimeBus });
- * lcm.scanAndRegister();
- * ```
- */
-
-export type {
-  PluginCapability,
-  PluginCapabilityManifest,
-  PluginManifestV2,
-  PluginTransition,
-  TransitionResult,
-  PluginHealthCheckResult,
-  PluginLifecycleRecord,
-  PluginLifecycleManagerOptions,
-  PluginLifecycleState,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-
-export { ALL_CAPABILITIES, MAX_TRANSITION_HISTORY } from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-
-export {
-  VALID_TRANSITIONS,
-  canTransition,
-  applyTransition,
-  isOperational,
-  isReloadable,
-  isTerminal,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/lifecycle';
-
-export {
-  resolveCapabilityManifest,
-  hasCapability,
-  validateManifestV2,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/manifest';
-
-export { PluginLifecycleManager } from '@pellux/goodvibes-sdk/platform/runtime/plugins/manager';
-import { PluginLifecycleManager } from '@pellux/goodvibes-sdk/platform/runtime/plugins/manager';
-
-// Trust framework.
-export type {
-  PluginTrustTier,
-  PluginTrustRecord,
-  SignatureValidationResult,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/trust';
-export {
-  PluginTrustStore,
-  validatePluginSignature,
-  filterCapabilitiesByTrust,
-  SAFE_CAPABILITIES,
-} from '@pellux/goodvibes-sdk/platform/runtime/plugins/trust';
-
-export type { QuarantineRecord } from '@pellux/goodvibes-sdk/platform/runtime/plugins/quarantine';
-export { PluginQuarantineEngine } from '@pellux/goodvibes-sdk/platform/runtime/plugins/quarantine';
-
-export { isHighRiskCapability } from '@pellux/goodvibes-sdk/platform/runtime/plugins/manifest';
-
-export type { HotReloadOptions, HotReloadResult } from '@pellux/goodvibes-sdk/platform/runtime/plugins/hot-reload';
-export { runHotReload } from '@pellux/goodvibes-sdk/platform/runtime/plugins/hot-reload';
-
-/**
- * createPluginLifecycleManager — Factory function for the PluginLifecycleManager.
- *
- * Intended as the primary entry point for consumers. Respects the
- * `plugin-lifecycle` feature flag — callers should check the flag before
- * invoking if they want to gate the entire system.
- *
- * @param options - Optional manager configuration.
- * @returns A new PluginLifecycleManager instance.
- */
-export function createPluginLifecycleManager(
-  options: import('./types.ts').PluginLifecycleManagerOptions = {},
-): PluginLifecycleManager {
-  return new PluginLifecycleManager(options);
-}

package/src/runtime/plugins/lifecycle.ts

@@ -1,95 +0,0 @@
-/**
- * Plugin lifecycle state machine.
- *
- * Defines the valid state transitions for the 8-state plugin lifecycle
- * and provides pure guard/transition functions with no side effects.
- *
- * States:
- *   discovered → loading → loaded → active ↔ degraded
- *                                          ↓
- *                                        error → (unloading | disabled)
- *                    active/loaded/degraded/error → unloading → disabled
- *                    any → error (non-fatal)
- *                    disabled → loading (re-enable)
- */
-
-import type { PluginLifecycleState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/plugins';
-import type { TransitionResult } from '@pellux/goodvibes-sdk/platform/runtime/plugins/types';
-
-/**
- * Adjacency map: from state → set of valid target states.
- *
- * Encoded as a plain Record so it is safe to evaluate at module load time
- * with no external dependencies.
- */
-export const VALID_TRANSITIONS: Readonly<
-  Record<PluginLifecycleState, ReadonlyArray<PluginLifecycleState>>
-> = {
-  discovered: ['loading'],
-  loading:    ['loaded', 'error'],
-  loaded:     ['active', 'error', 'unloading'],
-  active:     ['degraded', 'error', 'unloading'],
-  degraded:   ['active', 'error', 'unloading'],
-  error:      ['unloading', 'disabled', 'loading'],
-  unloading:  ['disabled'],
-  disabled:   ['loading'],
-} as const;
-
-/**
- * Returns whether a transition from `from` → `to` is permitted by the
- * state machine.
- */
-export function canTransition(
-  from: PluginLifecycleState,
-  to: PluginLifecycleState,
-): boolean {
-  return (VALID_TRANSITIONS[from] as ReadonlyArray<PluginLifecycleState>).includes(to);
-}
-
-/**
- * Attempts a state transition and returns a typed result.
- *
- * This is a pure function — it has no side effects. The caller is responsible
- * for updating the plugin record and emitting events.
- *
- * @param from - Current state.
- * @param to   - Desired target state.
- * @returns `{ ok: true, from, to }` on success or `{ ok: false, reason }` on
- *          invalid transition.
- */
-export function applyTransition(
-  from: PluginLifecycleState,
-  to: PluginLifecycleState,
-): TransitionResult {
-  if (canTransition(from, to)) {
-    return { ok: true, from, to };
-  }
-  return {
-    ok: false,
-    reason: `Invalid transition: ${from} → ${to} (allowed from ${from}: [${VALID_TRANSITIONS[from].join(', ')}])`,
-  };
-}
-
-/**
- * Returns whether a plugin in the given state is considered "operational"
- * (i.e. actively servicing requests, possibly in a degraded capacity).
- */
-export function isOperational(state: PluginLifecycleState): boolean {
-  return state === 'active' || state === 'degraded';
-}
-
-/**
- * Returns whether a plugin in the given state can be safely hot-reloaded.
- * A hot reload requires the plugin to be quiesceable.
- */
-export function isReloadable(state: PluginLifecycleState): boolean {
-  return state === 'active' || state === 'loaded' || state === 'degraded' || state === 'error';
-}
-
-/**
- * Returns whether the plugin's current state represents a terminal failure
- * that requires operator intervention (disabled or persistent error).
- */
-export function isTerminal(state: PluginLifecycleState): boolean {
-  return state === 'disabled';
-}