fluxplugin 1.0.0

package/dist/node/index.js

@@ -0,0 +1,138 @@
+import {
+  BUILTIN_PERMISSIONS,
+  CHANNELS,
+  CommandRegistry,
+  DisposableStore,
+  EventBus,
+  ExtensionPointRegistry,
+  FRAMEWORK_ENGINE_KEY,
+  FRAMEWORK_VERSION,
+  FrameworkError,
+  HookCancelledError,
+  HookSystem,
+  IpcError,
+  IpcRegistry,
+  LifecycleError,
+  LogStore,
+  MGMT,
+  MemoryStorageBackend,
+  MenuRegistry,
+  PermissionDeniedError,
+  PermissionManager,
+  PluginManager,
+  PreloadRegistry,
+  Registry,
+  RouteRegistry,
+  ServiceRegistry,
+  SlotRegistry,
+  StyleRegistry,
+  TimeoutError,
+  ValidationError,
+  activationOrderFor,
+  buildDependencyGraph,
+  compareVersions,
+  createPluginConfig,
+  createPluginState,
+  createPluginStorage,
+  defineCommand,
+  defineComponent,
+  defineEvent,
+  defineHook,
+  defineIPC,
+  defineIpcContract,
+  defineMenu,
+  definePlugin,
+  defineRoute,
+  defineService,
+  dependentsOf,
+  describeIssue,
+  errorMessage,
+  hasPluginApi,
+  isValidRange,
+  isValidVersion,
+  manifestSchema,
+  matchesPattern,
+  menuLocations,
+  normalizePath,
+  parseOrThrow,
+  parseVersion,
+  pluginApi,
+  preloadMember,
+  routePatternMatches,
+  s,
+  satisfies,
+  scopeCss,
+  serializeError,
+  toDisposable,
+  validateManifest,
+  withTimeout
+} from "./chunks/chunk-XPLGAEBH.js";
+export {
+  BUILTIN_PERMISSIONS,
+  CHANNELS,
+  CommandRegistry,
+  DisposableStore,
+  EventBus,
+  ExtensionPointRegistry,
+  FRAMEWORK_ENGINE_KEY,
+  FRAMEWORK_VERSION,
+  FrameworkError,
+  HookCancelledError,
+  HookSystem,
+  IpcError,
+  IpcRegistry,
+  LifecycleError,
+  LogStore,
+  MGMT,
+  MemoryStorageBackend,
+  MenuRegistry,
+  PermissionDeniedError,
+  PermissionManager,
+  PluginManager,
+  PreloadRegistry,
+  Registry,
+  RouteRegistry,
+  ServiceRegistry,
+  SlotRegistry,
+  StyleRegistry,
+  TimeoutError,
+  ValidationError,
+  activationOrderFor,
+  buildDependencyGraph,
+  compareVersions,
+  createPluginConfig,
+  createPluginState,
+  createPluginStorage,
+  defineCommand,
+  defineComponent,
+  defineEvent,
+  defineHook,
+  defineIPC,
+  defineIpcContract,
+  defineMenu,
+  definePlugin,
+  defineRoute,
+  defineService,
+  dependentsOf,
+  describeIssue,
+  errorMessage,
+  hasPluginApi,
+  isValidRange,
+  isValidVersion,
+  manifestSchema,
+  matchesPattern,
+  menuLocations,
+  normalizePath,
+  parseOrThrow,
+  parseVersion,
+  pluginApi,
+  preloadMember,
+  routePatternMatches,
+  s,
+  satisfies,
+  scopeCss,
+  serializeError,
+  toDisposable,
+  validateManifest,
+  withTimeout
+};

package/dist/node/main.js

@@ -0,0 +1,61 @@
+import {
+  FsStorageBackend,
+  HttpRegistry,
+  IntegrityError,
+  JsonStateFile,
+  LocalRegistry,
+  MANIFEST_FILE,
+  MainFramework,
+  PLUGIN_SCHEME,
+  PluginInstaller,
+  attachElectron,
+  attachHttp,
+  canonicalJson,
+  computeIntegrity,
+  copyDir,
+  createLoopbackBridge,
+  createTarGz,
+  discoverPlugins,
+  extractTarGz,
+  generateSigningKeyPair,
+  importFresh,
+  readPluginDir,
+  readTarGz,
+  registerPluginProtocol,
+  resolvePluginAsset,
+  serveWeb,
+  sha256File,
+  signManifest,
+  verifyPlugin
+} from "./chunks/chunk-BZ7NZF7I.js";
+import "./chunks/chunk-XPLGAEBH.js";
+export {
+  FsStorageBackend,
+  HttpRegistry,
+  IntegrityError,
+  JsonStateFile,
+  LocalRegistry,
+  MANIFEST_FILE,
+  MainFramework,
+  PLUGIN_SCHEME,
+  PluginInstaller,
+  attachElectron,
+  attachHttp,
+  canonicalJson,
+  computeIntegrity,
+  copyDir,
+  createLoopbackBridge,
+  createTarGz,
+  discoverPlugins,
+  extractTarGz,
+  generateSigningKeyPair,
+  importFresh,
+  readPluginDir,
+  readTarGz,
+  registerPluginProtocol,
+  resolvePluginAsset,
+  serveWeb,
+  sha256File,
+  signManifest,
+  verifyPlugin
+};

package/dist/node/preload.js

@@ -0,0 +1,56 @@
+import {
+  CHANNELS
+} from "./chunks/chunk-XPLGAEBH.js";
+
+// src/preload/index.ts
+var IpcCallError = class extends Error {
+  constructor(payload) {
+    super(payload.message);
+    this.payload = payload;
+    this.name = "IpcCallError";
+  }
+  payload;
+  get code() {
+    return this.payload.code;
+  }
+};
+function createBridge(ipcRenderer) {
+  const listeners = /* @__PURE__ */ new Map();
+  ipcRenderer.on(CHANNELS.event, (_e, msg) => {
+    if (!msg || typeof msg.channel !== "string") return;
+    for (const l of [...listeners.get(msg.channel) ?? []]) {
+      try {
+        l(msg.payload);
+      } catch {
+      }
+    }
+  });
+  return {
+    async invoke(channel, input, caller) {
+      const req = { channel: String(channel), input, caller };
+      const res = await ipcRenderer.invoke(CHANNELS.invoke, req);
+      if (!res.ok) throw new IpcCallError(res.error);
+      return res.value;
+    },
+    send(channel, payload, caller) {
+      ipcRenderer.send(CHANNELS.send, { channel: String(channel), payload, caller });
+    },
+    on(channel, listener) {
+      let set = listeners.get(channel);
+      if (!set) listeners.set(channel, set = /* @__PURE__ */ new Set());
+      set.add(listener);
+      return () => void set.delete(listener);
+    },
+    bootstrap: () => ipcRenderer.invoke(CHANNELS.bootstrap)
+  };
+}
+function exposeFluxBridge(contextBridge, ipcRenderer, key = "__fluxplugin") {
+  const bridge = createBridge(ipcRenderer);
+  contextBridge.exposeInMainWorld(key, bridge);
+  return bridge;
+}
+export {
+  IpcCallError,
+  createBridge,
+  exposeFluxBridge
+};

package/dist/types/cli/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/build.d.ts

@@ -0,0 +1,7 @@
+import { type BuildOptions } from "esbuild";
+/** Convention: dist/X is built from src/X (main.ts, renderer.tsx, styles/*.css). */
+export declare function buildOptions(root: string): Promise<BuildOptions[]>;
+export declare function buildPlugin(root: string, watch?: boolean, log?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}): Promise<() => Promise<void>>;

package/dist/types/cli/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function readManifest(root: string): Promise<Record<string, unknown>>;
+export declare function run(argv: string[]): Promise<number>;

package/dist/types/cli/config.d.ts

@@ -0,0 +1,9 @@
+export interface CliConfig {
+    pluginsDir: string;
+    dataDir: string;
+}
+/** Resolves `--dir/--data` flags, then `fluxplugin.config.json` in the cwd, then defaults. */
+export declare function loadConfig(flags: {
+    dir?: string;
+    data?: string;
+}, cwd?: string): Promise<CliConfig>;

package/dist/types/cli/host-templates.d.ts

@@ -0,0 +1,6 @@
+export interface HostVars {
+    name: string;
+    fluxSpec: string;
+}
+/** Files of a new host application (`fluxplugin init`). Plain strings so the CLI stays a single self-contained file. */
+export declare function hostFiles(v: HostVars, withSample?: boolean): Record<string, string>;

package/dist/types/cli/host.d.ts

@@ -0,0 +1,16 @@
+import { type ChildProcess } from "node:child_process";
+export declare function isHostProject(cwd: string): Promise<boolean>;
+/** Bundles the host (renderer, main, preload, web) and every plugin in `pluginsDir`. */
+export declare function buildHost(cwd: string, opts?: {
+    watch?: boolean;
+    log?: (m: string) => void;
+}): Promise<() => Promise<void>>;
+/** Starts the app: Electron when available (unless `web`), otherwise browser mode. Resolves when it exits. */
+export declare function startApp(cwd: string, opts?: {
+    web?: boolean;
+    dev?: boolean;
+    port?: number;
+}): {
+    child: ChildProcess;
+    mode: "electron" | "web";
+};

package/dist/types/cli/index.d.ts

@@ -0,0 +1,6 @@
+export { run } from "./cli.js";
+export { buildPlugin } from "./build.js";
+export * from "./templates.js";
+export { sharedModulesPlugin, SHARED_MODULES } from "./shared-modules.js";
+export { buildHost, startApp, isHostProject } from "./host.js";
+export { hostFiles } from "./host-templates.js";

package/dist/types/cli/shared-modules.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from "esbuild";
+/** Modules provided by the host at runtime through `globalThis.__FLUXPLUGIN_SHARED__` (single instance of React, the runtime...). */
+export declare const SHARED_MODULES: string[];
+/**
+ * esbuild plugin rewriting imports of shared modules to `globalThis.__FLUXPLUGIN_SHARED__[id]`.
+ * Without it each plugin bundle would ship its own React and hooks would break (two React copies).
+ */
+export declare function sharedModulesPlugin(shared?: string[]): Plugin;

package/dist/types/cli/templates.d.ts

@@ -0,0 +1,10 @@
+export type TemplateName = "basic" | "dashboard" | "backend";
+export interface TemplateVars {
+    id: string;
+    name: string;
+    /** Short identifier usable as JS identifier / IPC prefix. */
+    slug: string;
+    Pascal: string;
+}
+export declare const TEMPLATES: Record<TemplateName, (v: TemplateVars) => Record<string, string>>;
+export declare function varsFromName(name: string): TemplateVars;

package/dist/types/core/api.d.ts

@@ -0,0 +1,11 @@
+import type { PluginApis } from "./ipc.js";
+/**
+ * Typed access to `window.plugins.<namespace>` in renderer code. Augment `PluginApis` to describe the API:
+ *
+ * ```ts
+ * declare module "fluxplugin" { interface PluginApis { analytics: { getStats(): Promise<Stats> } } }
+ * const stats = await pluginApi("analytics").getStats();
+ * ```
+ */
+export declare function pluginApi<K extends keyof PluginApis & string>(namespace: K): PluginApis[K];
+export declare function hasPluginApi(namespace: string): boolean;

package/dist/types/core/common.d.ts

@@ -0,0 +1,69 @@
+export interface Disposable {
+    dispose(): void;
+}
+export declare const toDisposable: (fn: () => void) => Disposable;
+/** Collects disposables so that everything a plugin registered is removed when the plugin deactivates. */
+export declare class DisposableStore implements Disposable {
+    private items;
+    private disposed;
+    add<T extends Disposable>(d: T): T;
+    get size(): number;
+    dispose(): void;
+    /** Re-arms the store so it can be reused after a deactivate/activate cycle. */
+    reset(): void;
+}
+export declare class FrameworkError extends Error {
+    readonly code: string;
+    readonly pluginId?: string | undefined;
+    constructor(message: string, code: string, pluginId?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+export declare class PermissionDeniedError extends FrameworkError {
+    readonly permission: string;
+    constructor(pluginId: string, permission: string, api: string);
+}
+export declare class LifecycleError extends FrameworkError {
+    readonly phase: string;
+    constructor(pluginId: string, phase: string, message: string, cause?: unknown);
+}
+export declare class TimeoutError extends FrameworkError {
+    constructor(what: string, ms: number, pluginId?: string);
+}
+export declare class HookCancelledError extends FrameworkError {
+    readonly operation: string;
+    readonly reason?: string | undefined;
+    constructor(operation: string, reason?: string | undefined);
+}
+export declare function withTimeout<T>(p: Promise<T> | T, ms: number, what: string, pluginId?: string): Promise<T>;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    level: LogLevel;
+    source: string;
+    message: string;
+    time: number;
+    data?: unknown;
+}
+export interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/** In-memory ring buffer of log entries, queryable per plugin (used for diagnostics in the manager UI). */
+export declare class LogStore {
+    private readonly capacity;
+    private readonly sink?;
+    private entries;
+    private listeners;
+    constructor(capacity?: number, sink?: ((e: LogEntry) => void) | undefined);
+    write(entry: LogEntry): void;
+    logger(source: string): Logger;
+    query(filter?: {
+        source?: string;
+        level?: LogLevel;
+    }): LogEntry[];
+    subscribe(l: (e: LogEntry) => void): Disposable;
+    clear(source?: string): void;
+}
+export declare function errorMessage(e: unknown): string;

package/dist/types/core/deps.d.ts

@@ -0,0 +1,34 @@
+import type { PluginManifest } from "./manifest.js";
+export type DependencyIssue = {
+    type: "missing";
+    plugin: string;
+    dependency: string;
+    range: string;
+    kind: "dependencies" | "peerDependencies";
+} | {
+    type: "version";
+    plugin: string;
+    dependency: string;
+    range: string;
+    found: string;
+} | {
+    type: "cycle";
+    plugin: string;
+    path: string[];
+};
+export interface DependencyGraph {
+    manifests: Map<string, PluginManifest>;
+    /** Hard edges (dependencies + peerDependencies) plus optional ones that are installed. */
+    edges: Map<string, string[]>;
+    issues: DependencyIssue[];
+    /** Plugins that cannot be activated because of an issue (own or inherited from a dependency). */
+    blocked: Set<string>;
+    /** Global topological order (dependencies first) of every non-blocked plugin. */
+    order: string[];
+}
+export declare function buildDependencyGraph(manifests: Iterable<PluginManifest>): DependencyGraph;
+/** `id` preceded by all of its transitive dependencies, dependencies first. */
+export declare function activationOrderFor(graph: DependencyGraph, id: string): string[];
+/** Plugins that (transitively) require `id`, ordered so that each one comes before what it depends on (safe deactivation order). */
+export declare function dependentsOf(graph: DependencyGraph, id: string): string[];
+export declare function describeIssue(i: DependencyIssue): string;

package/dist/types/core/events.d.ts

@@ -0,0 +1,58 @@
+import { type Disposable } from "./common.js";
+export interface EventContext<P = unknown> {
+    /** Concrete event name that was emitted (never a pattern). */
+    readonly name: string;
+    readonly payload: P;
+    /** Plugin / component that emitted the event, when known. */
+    readonly source?: string;
+    readonly cancelled: boolean;
+    /** Stops propagation to lower-priority listeners and flags the emission as cancelled. */
+    cancel(): void;
+}
+export type EventListener<P = unknown> = (payload: P, ctx: EventContext<P>) => void | Promise<void>;
+export interface ListenerOptions {
+    /** Higher runs first. Default 0. */
+    priority?: number;
+    once?: boolean;
+}
+export interface EmitResult {
+    cancelled: boolean;
+    errors: unknown[];
+    delivered: number;
+}
+export declare function matchesPattern(pattern: string, name: string): boolean;
+/**
+ * Typed event bus. `M` maps event names to payload types:
+ *
+ * ```ts
+ * const bus = new EventBus<{ "user.created": { id: string } }>();
+ * bus.on("user.created", (u) => u.id);
+ * bus.on("user.*", (payload, ctx) => ctx.name);
+ * ```
+ */
+export declare class EventBus<M extends Record<string, any> = Record<string, any>> {
+    private readonly onError;
+    private entries;
+    private seq;
+    constructor(onError?: (error: unknown, eventName: string, pattern: string) => void);
+    on<K extends keyof M & string>(name: K, listener: EventListener<M[K]>, opts?: ListenerOptions): Disposable;
+    on(pattern: string, listener: EventListener<any>, opts?: ListenerOptions): Disposable;
+    once<K extends keyof M & string>(name: K, listener: EventListener<M[K]>, opts?: Omit<ListenerOptions, "once">): Disposable;
+    once(pattern: string, listener: EventListener<any>, opts?: Omit<ListenerOptions, "once">): Disposable;
+    off(pattern: string, listener: EventListener<any>): void;
+    listenerCount(pattern?: string): number;
+    removeAll(): void;
+    private matching;
+    /** Synchronous emit. Async listeners are started but not awaited (their rejections go to `onError`). */
+    emit<K extends keyof M & string>(name: K, payload: M[K], source?: string): EmitResult;
+    emit(name: string, payload?: unknown, source?: string): EmitResult;
+    /** Awaits every listener sequentially (priority order). */
+    emitAsync<K extends keyof M & string>(name: K, payload: M[K], source?: string): Promise<EmitResult>;
+    emitAsync(name: string, payload?: unknown, source?: string): Promise<EmitResult>;
+    /** Resolves with the payload of the next matching event. */
+    waitFor<K extends keyof M & string>(name: K, timeoutMs?: number): Promise<M[K]>;
+    waitFor(pattern: string, timeoutMs?: number): Promise<unknown>;
+    private removeEntry;
+    private fail;
+    private makeCtx;
+}

package/dist/types/core/hooks.d.ts

@@ -0,0 +1,55 @@
+import { type Disposable } from "./common.js";
+export type HookKind = "before" | "after" | "around" | "transform" | "validate" | "filter";
+export interface HookContext<I = any, R = any> {
+    /** Operation name without the kind prefix, e.g. `user.create`. */
+    readonly operation: string;
+    /** Mutable input: `before` hooks may replace or edit it. */
+    input: I;
+    /** Result of the operation (available to `transform` and `after` hooks). */
+    result: R | undefined;
+    readonly cancelled: boolean;
+    readonly cancelReason: string | undefined;
+    /** Aborts the operation; `run()` rejects with `HookCancelledError`. */
+    cancel(reason?: string): void;
+    /** Shared scratch space between hooks of one run. */
+    readonly data: Map<string, unknown>;
+}
+export type AroundNext<R> = () => Promise<R>;
+export type HookHandler<I = any, R = any> = ((ctx: HookContext<I, R>) => void | Promise<void>) | ((ctx: HookContext<I, R>) => R | Promise<R> | void | Promise<void>) | ((ctx: HookContext<I, R>, next: AroundNext<R>) => Promise<R> | R) | ((value: any, extra?: any) => any);
+export interface HookOptions {
+    priority?: number;
+    owner?: string;
+}
+/**
+ * Hook pipeline. Hosts wrap their operations with `run()`; plugins attach behaviours with `use()`.
+ *
+ * Execution order of `run("user.create", input, exec)`:
+ *   validate → before → around (onion) → exec → transform → after
+ *
+ * `before`/`validate` may mutate `ctx.input`, call `ctx.cancel()` or throw to block the operation.
+ * `transform` may replace the result by returning a value. `after` is observational: errors are swallowed
+ * (reported through `onError`) so they cannot corrupt an operation that already succeeded.
+ */
+export declare class HookSystem {
+    private readonly onError;
+    private entries;
+    private seq;
+    constructor(onError?: (error: unknown, hookName: string, owner?: string) => void);
+    use<I = any, R = any>(name: `before.${string}` | `after.${string}` | `validate.${string}` | `transform.${string}`, handler: (ctx: HookContext<I, R>) => any, opts?: HookOptions): Disposable;
+    use<I = any, R = any>(name: `around.${string}`, handler: (ctx: HookContext<I, R>, next: AroundNext<R>) => any, opts?: HookOptions): Disposable;
+    use<V = any, X = any>(name: `filter.${string}`, handler: (value: V, extra?: X) => V | Promise<V>, opts?: HookOptions): Disposable;
+    count(kind?: HookKind, operation?: string): number;
+    list(): {
+        kind: HookKind;
+        operation: string;
+        priority: number;
+        owner?: string;
+    }[];
+    private get;
+    run<I, R>(operation: string, input: I, exec: (input: I, ctx: HookContext<I, R>) => R | Promise<R>): Promise<R>;
+    /** Runs `filter.<name>` handlers as a value pipeline. A failing filter is skipped and reported. */
+    filter<V, X = unknown>(name: string, value: V, extra?: X): Promise<V>;
+    /** Synchronous variant for render-time filters (async filters are ignored with a reported error). */
+    filterSync<V, X = unknown>(name: string, value: V, extra?: X): V;
+    removeByOwner(owner: string): void;
+}

package/dist/types/core/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./common.js";
+export * from "./schema.js";
+export * from "./semver.js";
+export * from "./manifest.js";
+export * from "./events.js";
+export * from "./hooks.js";
+export * from "./permissions.js";
+export * from "./registry.js";
+export * from "./routes.js";
+export * from "./slots.js";
+export * from "./styles.js";
+export * from "./ipc.js";
+export * from "./storage.js";
+export * from "./deps.js";
+export * from "./plugin.js";
+export * from "./manager.js";
+export * from "./protocol.js";
+export * from "./api.js";