@forgeportal/plugin-sdk 1.0.0

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAMA,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIzC,OAAO,EACL,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAGjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,GAAG,OAAO,EACpC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,GAC7D,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAkB9B"}

package/dist/react.js

@@ -0,0 +1,65 @@
+/**
+ * React hooks and context providers for use inside plugin UI components
+ * and the ForgePortal UI app shell.
+ * Import from: @forgeportal/plugin-sdk/react
+ */
+import { useCallback } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useEntityContext, usePluginConfigContext } from './context.js';
+// ─── Re-export React context providers for the app shell ─────────────────────
+// These are used by EntityDetailPage and EntityOverviewTab to wrap plugin components.
+export { EntityProvider, EntityContext, PluginConfigProvider, PluginConfigContext, } from './context.js';
+/**
+ * Returns the current entity from the entity detail page context.
+ * Must be used inside a component rendered as an EntityTab or EntityCard.
+ *
+ * @throws if called outside of an EntityProvider.
+ */
+export function useEntity() {
+    const ctx = useEntityContext();
+    if (!ctx) {
+        throw new Error('[ForgePortal SDK] useEntity() must be called inside an EntityTab or EntityCard component. ' +
+            'Ensure this component is registered via sdk.registerEntityTab() or sdk.registerEntityCard().');
+    }
+    return ctx;
+}
+/**
+ * Returns the plugin-scoped config value for the given key.
+ * Config is sourced from `forgeportal.yaml` -> `plugins.<pluginId>.config`.
+ *
+ * @example
+ * const apiUrl = useConfig<string>('apiEndpoint');
+ */
+export function useConfig(key) {
+    const config = usePluginConfigContext();
+    return config.get(key);
+}
+/**
+ * Typed API fetcher backed by TanStack Query.
+ * Automatically includes credentials for session-based auth.
+ *
+ * @param path    - Absolute API path, e.g. '/api/v1/entities'
+ * @param options - Optional TanStack Query options to override defaults
+ *
+ * @example
+ * const { data, isPending } = useApi<MyResponse[]>('/api/v1/my-plugin/data');
+ */
+export function useApi(path, options) {
+    const queryFn = useCallback(async () => {
+        const res = await fetch(path, {
+            headers: { 'Accept': 'application/json' },
+            credentials: 'include',
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => res.statusText);
+            throw new Error(`[ForgePortal SDK] API ${path} returned ${res.status}: ${text}`);
+        }
+        return res.json();
+    }, [path]);
+    return useQuery({
+        queryKey: ['forge-plugin-api', path],
+        queryFn,
+        ...options,
+    });
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,QAAQ,EAA6C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGxE,gFAAgF;AAChF,sFAAsF;AACtF,OAAO,EACL,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,4FAA4F;YAC5F,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAc,GAAW;IAChD,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;IACxC,OAAO,MAAM,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CACpB,IAAY,EACZ,OAA8D;IAE9D,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAoB,EAAE;QACrD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE;YAC5B,OAAO,EAAM,EAAE,QAAQ,EAAE,kBAAkB,EAAE;YAC7C,WAAW,EAAE,SAAS;SACvB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC1D,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,aAAa,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAAoB,CAAC;IACtC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,OAAO,QAAQ,CAAe;QAC5B,QAAQ,EAAE,CAAC,kBAAkB,EAAE,IAAI,CAAC;QACpC,OAAO;QACP,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,31 @@
+import type { ForgePluginSDK, EntityTab, EntityCard, Route, ActionProvider, CatalogProvider } from './types.js';
+/**
+ * In-memory registry — the canonical implementation of ForgePluginSDK.
+ * Instantiated once per app (API or UI) at startup.
+ * Plugins receive this as the `sdk` argument in `registerPlugin(sdk)`.
+ */
+export declare class PluginRegistry implements ForgePluginSDK {
+    private readonly _entityTabs;
+    private readonly _entityCards;
+    private readonly _routes;
+    private readonly _actionProviders;
+    private readonly _catalogProviders;
+    registerEntityTab(tab: EntityTab): void;
+    registerEntityCard(card: EntityCard): void;
+    registerRoute(route: Route): void;
+    registerActionProvider(provider: ActionProvider): void;
+    registerCatalogProvider(provider: CatalogProvider): void;
+    /**
+     * Returns entity tabs, optionally filtered by entity kind.
+     * Tabs with no `appliesTo.kinds` constraint match all kinds.
+     */
+    getEntityTabs(entityKind?: string): EntityTab[];
+    getEntityCards(entityKind?: string): EntityCard[];
+    getRoutes(): Route[];
+    getActionProviders(): ActionProvider[];
+    getActionProvider(id: string, version: string): ActionProvider | undefined;
+    getCatalogProviders(): CatalogProvider[];
+}
+/** Global singleton — used by the app shell (API and UI). */
+export declare const globalRegistry: PluginRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,UAAU,EACV,KAAK,EACL,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,qBAAa,cAAe,YAAW,cAAc;IACnD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IAExE,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAQvC,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQ1C,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAQjC,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAStD,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAUxD;;;OAGG;IACH,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAQ/C,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAQjD,SAAS,IAAI,KAAK,EAAE;IAIpB,kBAAkB,IAAI,cAAc,EAAE;IAItC,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI1E,mBAAmB,IAAI,eAAe,EAAE;CAGzC;AAED,6DAA6D;AAC7D,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/dist/registry.js

@@ -0,0 +1,80 @@
+/**
+ * In-memory registry — the canonical implementation of ForgePluginSDK.
+ * Instantiated once per app (API or UI) at startup.
+ * Plugins receive this as the `sdk` argument in `registerPlugin(sdk)`.
+ */
+export class PluginRegistry {
+    _entityTabs = new Map();
+    _entityCards = new Map();
+    _routes = new Map();
+    _actionProviders = new Map();
+    _catalogProviders = new Map();
+    registerEntityTab(tab) {
+        if (this._entityTabs.has(tab.id)) {
+            console.warn(`[ForgePortal SDK] EntityTab "${tab.id}" already registered — skipping duplicate.`);
+            return;
+        }
+        this._entityTabs.set(tab.id, tab);
+    }
+    registerEntityCard(card) {
+        if (this._entityCards.has(card.id)) {
+            console.warn(`[ForgePortal SDK] EntityCard "${card.id}" already registered — skipping duplicate.`);
+            return;
+        }
+        this._entityCards.set(card.id, card);
+    }
+    registerRoute(route) {
+        if (this._routes.has(route.path)) {
+            console.warn(`[ForgePortal SDK] Route "${route.path}" already registered — skipping duplicate.`);
+            return;
+        }
+        this._routes.set(route.path, route);
+    }
+    registerActionProvider(provider) {
+        const key = `${provider.id}@${provider.version}`;
+        if (this._actionProviders.has(key)) {
+            console.warn(`[ForgePortal SDK] ActionProvider "${key}" already registered — skipping duplicate.`);
+            return;
+        }
+        this._actionProviders.set(key, provider);
+    }
+    registerCatalogProvider(provider) {
+        if (this._catalogProviders.has(provider.id)) {
+            console.warn(`[ForgePortal SDK] CatalogProvider "${provider.id}" already registered — skipping duplicate.`);
+            return;
+        }
+        this._catalogProviders.set(provider.id, provider);
+    }
+    // ─── Getters (used by the app shell to read registered capabilities) ────────
+    /**
+     * Returns entity tabs, optionally filtered by entity kind.
+     * Tabs with no `appliesTo.kinds` constraint match all kinds.
+     */
+    getEntityTabs(entityKind) {
+        const all = Array.from(this._entityTabs.values());
+        if (!entityKind)
+            return all;
+        return all.filter(t => !t.appliesTo?.kinds || t.appliesTo.kinds.includes(entityKind));
+    }
+    getEntityCards(entityKind) {
+        const all = Array.from(this._entityCards.values());
+        if (!entityKind)
+            return all;
+        return all.filter(c => !c.appliesTo?.kinds || c.appliesTo.kinds.includes(entityKind));
+    }
+    getRoutes() {
+        return Array.from(this._routes.values());
+    }
+    getActionProviders() {
+        return Array.from(this._actionProviders.values());
+    }
+    getActionProvider(id, version) {
+        return this._actionProviders.get(`${id}@${version}`);
+    }
+    getCatalogProviders() {
+        return Array.from(this._catalogProviders.values());
+    }
+}
+/** Global singleton — used by the app shell (API and UI). */
+export const globalRegistry = new PluginRegistry();
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,212 @@
+import type React from 'react';
+export interface Entity {
+    id: string;
+    kind: string;
+    namespace: string;
+    name: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    links?: Array<{
+        title: string;
+        url: string;
+    }>;
+    owner_ref?: string;
+    lifecycle?: string;
+    spec?: Record<string, unknown>;
+}
+export interface EntityDraft {
+    kind: string;
+    namespace: string;
+    name: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    links?: Array<{
+        title: string;
+        url: string;
+    }>;
+    owner_ref?: string;
+    lifecycle?: string;
+    spec?: Record<string, unknown>;
+    relations?: Array<{
+        type: string;
+        targetRef: string;
+    }>;
+    sources?: Array<{
+        kind: string;
+        url: string;
+        ref?: string;
+    }>;
+}
+export interface EntityTabAppliesTo {
+    kinds?: string[];
+    lifecycle?: string[];
+}
+export interface EntityTab {
+    id: string;
+    title: string;
+    /** Rendered inside the entity detail page tab panel. Receives the current entity. */
+    component: React.ComponentType<{
+        entity: Entity;
+    }>;
+    appliesTo?: EntityTabAppliesTo;
+}
+export interface EntityCard {
+    id: string;
+    title: string;
+    /** Rendered as a card on the entity overview tab. */
+    component: React.ComponentType<{
+        entity: Entity;
+    }>;
+    appliesTo?: {
+        kinds?: string[];
+    };
+}
+export interface Route {
+    /** URL path, e.g. '/pagerduty'. Must be globally unique. */
+    path: string;
+    component: React.ComponentType;
+    /** If provided, appears in the sidebar navigation. */
+    navLabel?: string;
+    /** Optional icon name or emoji character. */
+    icon?: string;
+}
+export type JsonSchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+export interface JsonSchema {
+    type: JsonSchemaType | JsonSchemaType[];
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    default?: unknown;
+    /** Set true to mark as secret — redacted in audit logs. */
+    'x-secret'?: boolean;
+}
+export interface ActionResult {
+    status: 'success' | 'failed';
+    outputs: Record<string, unknown>;
+    links?: Array<{
+        title: string;
+        url: string;
+    }>;
+    warnings?: string[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface ActionLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export interface ActionScmAccessor {
+    /** Returns file content as UTF-8 string, or null if not found. */
+    getFile(repoUrl: string, path: string, ref?: string): Promise<string | null>;
+    /** Lists file paths under prefix (streaming). */
+    listFiles(repoUrl: string, prefix?: string): AsyncIterable<string>;
+}
+export interface ActionDbAccessor {
+    /** Execute a read-only SQL query. Throws if the query mutates data. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+export interface ActionConfigAccessor {
+    /** Get a plugin-specific config value. Returns undefined if not set. */
+    get<T = unknown>(key: string): T | undefined;
+}
+/**
+ * Provided to every action handler at execution time.
+ * Exposes safe, scoped access to infrastructure services.
+ */
+export interface ActionContext {
+    /** Plugin-scoped config from forgeportal.yaml plugins.<pluginId>.config */
+    config: ActionConfigAccessor;
+    /** Structured logger — writes to action run logs visible in the UI. */
+    logger: ActionLogger;
+    /** SCM operations (getFile, listFiles). */
+    scm: ActionScmAccessor;
+    /** Read-only database access. */
+    db: ActionDbAccessor;
+    /**
+     * Acquires an advisory lock on a repository URL.
+     * Prevents concurrent SCM writes to the same repo within this action run.
+     * Automatically released when the action run completes.
+     */
+    acquireRepoLock(repoUrl: string): Promise<void>;
+    /**
+     * Append a log line to the current action run log (persisted in DB,
+     * visible in the Actions UI).
+     */
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string): Promise<void>;
+}
+export interface ActionProvider {
+    /** Globally unique action ID, e.g. "slack.sendMessage". */
+    id: string;
+    /** Semantic version string, e.g. "v1". */
+    version: string;
+    schema: {
+        input: JsonSchema;
+        output?: JsonSchema;
+    };
+    handler(ctx: ActionContext, input: Record<string, unknown>): Promise<ActionResult>;
+}
+export interface CatalogProviderContext {
+    logger: ActionLogger;
+    config: ActionConfigAccessor;
+}
+export interface CatalogProvider {
+    /** Globally unique provider ID, e.g. "pagerduty-catalog". */
+    id: string;
+    /** Called periodically by the worker to ingest entities from an external system. */
+    ingest(ctx: CatalogProviderContext): AsyncIterable<EntityDraft>;
+}
+/**
+ * The main SDK object passed to every plugin's `registerPlugin` function.
+ * Plugins call `sdk.registerXxx(...)` to expose their capabilities to ForgePortal.
+ */
+export interface ForgePluginSDK {
+    registerEntityTab(tab: EntityTab): void;
+    registerEntityCard(card: EntityCard): void;
+    registerRoute(route: Route): void;
+    registerActionProvider(provider: ActionProvider): void;
+    registerCatalogProvider(provider: CatalogProvider): void;
+}
+export interface PluginConfigFieldSchema {
+    type: 'string' | 'number' | 'boolean';
+    description?: string;
+    required?: boolean;
+    /** If true, the value must come from an env var and is never logged. */
+    secret?: boolean;
+    default?: string | number | boolean;
+}
+export interface PluginCapabilities {
+    ui?: {
+        entityTabs?: string[];
+        entityCards?: string[];
+        routes?: string[];
+    };
+    backend?: {
+        routes?: string[];
+        actionProviders?: string[];
+        catalogProviders?: string[];
+    };
+}
+export interface PluginManifest {
+    /** npm package name, e.g. "@myorg/forge-plugin-pagerduty" */
+    name: string;
+    version: string;
+    forgeportal: {
+        /** semver range against @forgeportal/plugin-sdk version, e.g. "^1.0.0" */
+        engineVersion: string;
+        type: 'ui' | 'backend' | 'fullstack';
+        capabilities: PluginCapabilities;
+        /** Required RBAC permissions, e.g. ["action:run"]. */
+        permissions?: string[];
+        /** Config field schemas declared by the plugin. */
+        config?: Record<string, PluginConfigFieldSchema>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,WAAW,MAAM;IACrB,EAAE,EAAY,MAAM,CAAC;IACrB,IAAI,EAAU,MAAM,CAAC;IACrB,SAAS,EAAK,MAAM,CAAC;IACrB,IAAI,EAAU,MAAM,CAAC;IACrB,KAAK,CAAC,EAAQ,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAS,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAQ,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,SAAS,CAAC,EAAI,MAAM,CAAC;IACrB,SAAS,CAAC,EAAI,MAAM,CAAC;IACrB,IAAI,CAAC,EAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAU,MAAM,CAAC;IACrB,SAAS,EAAK,MAAM,CAAC;IACrB,IAAI,EAAU,MAAM,CAAC;IACrB,KAAK,CAAC,EAAQ,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAS,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAQ,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,SAAS,CAAC,EAAI,MAAM,CAAC;IACrB,SAAS,CAAC,EAAI,MAAM,CAAC;IACrB,IAAI,CAAC,EAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,SAAS,CAAC,EAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,OAAO,CAAC,EAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAM,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAU,MAAM,CAAC;IACnB,KAAK,EAAO,MAAM,CAAC;IACnB,qFAAqF;IACrF,SAAS,EAAG,KAAK,CAAC,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAU,MAAM,CAAC;IACnB,KAAK,EAAO,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,EAAG,KAAK,CAAC,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAClC;AAED,MAAM,WAAW,KAAK;IACpB,4DAA4D;IAC5D,IAAI,EAAO,MAAM,CAAC;IAClB,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,IAAI,CAAC,EAAM,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAU,cAAc,GAAG,cAAc,EAAE,CAAC;IAChD,KAAK,CAAC,EAAQ,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAK,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAQ,UAAU,CAAC;IACzB,IAAI,CAAC,EAAS,OAAO,EAAE,CAAC;IACxB,OAAO,CAAC,EAAM,OAAO,CAAC;IACtB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAK,SAAS,GAAG,QAAQ,CAAC;IAChC,OAAO,EAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAK,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7E,iDAAiD;IACjD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,MAAM,EAAG,oBAAoB,CAAC;IAC9B,uEAAuE;IACvE,MAAM,EAAG,YAAY,CAAC;IACtB,2CAA2C;IAC3C,GAAG,EAAM,iBAAiB,CAAC;IAC3B,iCAAiC;IACjC,EAAE,EAAO,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,EAAE,EAAO,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACN,KAAK,EAAI,UAAU,CAAC;QACpB,MAAM,CAAC,EAAE,UAAU,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACpF;AAID,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,EAAE,EAAM,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,sBAAsB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;CACjE;AAID;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IACxC,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3C,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAClC,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACvD,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1D;AAID,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAU,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAK,OAAO,CAAC;IACtB,wEAAwE;IACxE,MAAM,CAAC,EAAO,OAAO,CAAC;IACtB,OAAO,CAAC,EAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE;QACH,UAAU,CAAC,EAAG,MAAM,EAAE,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,EAAO,MAAM,EAAE,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAa,MAAM,EAAE,CAAC;QAC7B,eAAe,CAAC,EAAI,MAAM,EAAE,CAAC;QAC7B,gBAAgB,CAAC,EAAG,MAAM,EAAE,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,IAAI,EAAK,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE;QACX,0EAA0E;QAC1E,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAW,IAAI,GAAG,SAAS,GAAG,WAAW,CAAC;QAC9C,YAAY,EAAG,kBAAkB,CAAC;QAClC,sDAAsD;QACtD,WAAW,CAAC,EAAG,MAAM,EAAE,CAAC;QACxB,mDAAmD;QACnD,MAAM,CAAC,EAAQ,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;KACxD,CAAC;CACH"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@forgeportal/plugin-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@forgeportal/core": "0.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "*",
+    "@types/react": "*",
+    "fastify": "^5.3.3",
+    "react": "*",
+    "vitest": "*"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
+  }
+}

package/src/backend.ts

@@ -0,0 +1,84 @@
+import type { FastifyInstance } from 'fastify';
+import type {
+  ActionProvider,
+  CatalogProvider,
+  ActionConfigAccessor,
+  ActionLogger,
+} from './types.js';
+
+/**
+ * A backend route registration — Fastify plugin function scoped under
+ * /api/v1/plugins/{pluginId}/{path}/
+ */
+export interface BackendRoute {
+  /** Relative path prefix, e.g. '/alerts'. No leading slash required. */
+  path:    string;
+  /**
+   * Fastify async plugin that registers route handlers.
+   * Receives a Fastify instance pre-scoped to the plugin's route prefix.
+   * Do NOT call fastify.listen() — only register routes.
+   */
+  handler: (fastify: FastifyInstance) => Promise<void>;
+}
+
+/**
+ * The SDK object passed to backend and fullstack plugin entry points.
+ * Distinct from ForgePluginSDK (which uses React components).
+ *
+ * Backend plugin entry: export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void
+ */
+export interface ForgeBackendPluginSDK {
+  /** Plugin-scoped config accessor (from forgeportal.yaml plugins.<id>.config). */
+  readonly config: ActionConfigAccessor;
+  /** Structured logger scoped to this plugin. */
+  readonly logger: ActionLogger;
+  /** Register an action provider (available in action runner + templates). */
+  registerActionProvider(provider: ActionProvider): void;
+  /** Register a catalog provider (periodic ingestion of external entities). */
+  registerCatalogProvider(provider: CatalogProvider): void;
+  /**
+   * Register backend routes under /api/v1/plugins/{pluginId}/{route.path}/
+   * The Fastify instance passed to handler is already authenticated (authGuard runs).
+   */
+  registerBackendRoute(route: BackendRoute): void;
+}
+
+/**
+ * Backend plugin registry — in-memory store for backend capabilities.
+ * Instantiated by the plugin loader for each plugin.
+ */
+export class BackendPluginRegistry implements ForgeBackendPluginSDK {
+  private readonly _actionProviders  = new Map<string, ActionProvider>();
+  private readonly _catalogProviders = new Map<string, CatalogProvider>();
+  private readonly _routes: BackendRoute[] = [];
+
+  constructor(
+    readonly config: ActionConfigAccessor,
+    readonly logger: ActionLogger,
+  ) {}
+
+  registerActionProvider(provider: ActionProvider): void {
+    const key = `${provider.id}@${provider.version}`;
+    if (this._actionProviders.has(key)) {
+      console.warn(`[ForgePortal SDK] ActionProvider "${key}" already registered — skipping.`);
+      return;
+    }
+    this._actionProviders.set(key, provider);
+  }
+
+  registerCatalogProvider(provider: CatalogProvider): void {
+    if (this._catalogProviders.has(provider.id)) {
+      console.warn(`[ForgePortal SDK] CatalogProvider "${provider.id}" already registered — skipping.`);
+      return;
+    }
+    this._catalogProviders.set(provider.id, provider);
+  }
+
+  registerBackendRoute(route: BackendRoute): void {
+    this._routes.push(route);
+  }
+
+  getActionProviders():  ActionProvider[]  { return [...this._actionProviders.values()]; }
+  getCatalogProviders(): CatalogProvider[] { return [...this._catalogProviders.values()]; }
+  getBackendRoutes():    BackendRoute[]    { return [...this._routes]; }
+}

package/src/context.tsx

@@ -0,0 +1,63 @@
+import React, { createContext, useContext } from 'react';
+import type { Entity } from './types.js';
+
+// ─── EntityContext ───────────────────────────────────────────────────────────
+
+interface EntityContextValue {
+  entity: Entity;
+}
+
+export const EntityContext = createContext<EntityContextValue | null>(null);
+
+export function EntityProvider({
+  entity,
+  children,
+}: {
+  entity:   Entity;
+  children: React.ReactNode;
+}) {
+  return (
+    <EntityContext.Provider value={{ entity }}>
+      {children}
+    </EntityContext.Provider>
+  );
+}
+
+// ─── PluginConfigContext ──────────────────────────────────────────────────────
+
+interface PluginConfigContextValue {
+  get<T = unknown>(key: string): T | undefined;
+}
+
+const defaultConfig: PluginConfigContextValue = {
+  get: () => undefined,
+};
+
+export const PluginConfigContext = createContext<PluginConfigContextValue>(defaultConfig);
+
+export function PluginConfigProvider({
+  config,
+  children,
+}: {
+  config:   Record<string, unknown>;
+  children: React.ReactNode;
+}) {
+  const accessor: PluginConfigContextValue = {
+    get: <T = unknown>(key: string) => config[key] as T | undefined,
+  };
+  return (
+    <PluginConfigContext.Provider value={accessor}>
+      {children}
+    </PluginConfigContext.Provider>
+  );
+}
+
+/** @internal Used by useEntity hook */
+export function useEntityContext(): EntityContextValue | null {
+  return useContext(EntityContext);
+}
+
+/** @internal Used by useConfig hook */
+export function usePluginConfigContext(): PluginConfigContextValue {
+  return useContext(PluginConfigContext);
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+// ─── Types ────────────────────────────────────────────────────────────────────
+export type {
+  Entity,
+  EntityDraft,
+  EntityTab,
+  EntityTabAppliesTo,
+  EntityCard,
+  Route,
+  JsonSchema,
+  JsonSchemaType,
+  ActionResult,
+  ActionLogger,
+  ActionScmAccessor,
+  ActionDbAccessor,
+  ActionConfigAccessor,
+  ActionContext,
+  ActionProvider,
+  CatalogProviderContext,
+  CatalogProvider,
+  ForgePluginSDK,
+  PluginConfigFieldSchema,
+  PluginCapabilities,
+  PluginManifest,
+} from './types.js';
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+export { PluginRegistry, globalRegistry } from './registry.js';
+
+// ─── Backend SDK (for backend and fullstack plugins) ─────────────────────────
+export type { BackendRoute, ForgeBackendPluginSDK } from './backend.js';
+export { BackendPluginRegistry } from './backend.js';
+
+// ─── SDK version (used by plugin loader for engineVersion compatibility check) ─
+export const SDK_VERSION = '1.0.0';