@forgeportal/plugin-sdk 1.0.0

package/src/react.ts

@@ -0,0 +1,80 @@
+/**
+ * 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, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import { useEntityContext, usePluginConfigContext } from './context.js';
+import type { Entity } from './types.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(): { entity: Entity } {
+  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<T = unknown>(key: string): T | undefined {
+  const config = usePluginConfigContext();
+  return config.get<T>(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<TData = unknown>(
+  path: string,
+  options?: Omit<UseQueryOptions<TData>, 'queryKey' | 'queryFn'>,
+): UseQueryResult<TData, Error> {
+  const queryFn = useCallback(async (): Promise<TData> => {
+    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() as Promise<TData>;
+  }, [path]);
+
+  return useQuery<TData, Error>({
+    queryKey: ['forge-plugin-api', path],
+    queryFn,
+    ...options,
+  });
+}

package/src/registry.ts

@@ -0,0 +1,103 @@
+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 class PluginRegistry implements ForgePluginSDK {
+  private readonly _entityTabs       = new Map<string, EntityTab>();
+  private readonly _entityCards      = new Map<string, EntityCard>();
+  private readonly _routes           = new Map<string, Route>();
+  private readonly _actionProviders  = new Map<string, ActionProvider>();
+  private readonly _catalogProviders = new Map<string, CatalogProvider>();
+
+  registerEntityTab(tab: EntityTab): void {
+    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: EntityCard): void {
+    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: Route): void {
+    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: ActionProvider): void {
+    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: CatalogProvider): void {
+    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?: string): EntityTab[] {
+    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?: string): EntityCard[] {
+    const all = Array.from(this._entityCards.values());
+    if (!entityKind) return all;
+    return all.filter(c =>
+      !c.appliesTo?.kinds || c.appliesTo.kinds.includes(entityKind),
+    );
+  }
+
+  getRoutes(): Route[] {
+    return Array.from(this._routes.values());
+  }
+
+  getActionProviders(): ActionProvider[] {
+    return Array.from(this._actionProviders.values());
+  }
+
+  getActionProvider(id: string, version: string): ActionProvider | undefined {
+    return this._actionProviders.get(`${id}@${version}`);
+  }
+
+  getCatalogProviders(): CatalogProvider[] {
+    return Array.from(this._catalogProviders.values());
+  }
+}
+
+/** Global singleton — used by the app shell (API and UI). */
+export const globalRegistry = new PluginRegistry();

package/src/types.ts

@@ -0,0 +1,221 @@
+import type React from 'react';
+
+// ─── Entity (subset of the catalog entity) ──────────────────────────────────
+
+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 }>;
+}
+
+// ─── Capability types ────────────────────────────────────────────────────────
+
+export interface EntityTabAppliesTo {
+  kinds?:     string[];     // e.g. ['service', 'library'] — undefined = all kinds
+  lifecycle?: string[];     // e.g. ['production'] — undefined = all lifecycles
+}
+
+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;
+}
+
+// ─── JSON Schema (minimal subset for action input/output) ───────────────────
+
+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;
+}
+
+// ─── Action Provider ─────────────────────────────────────────────────────────
+
+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>;
+}
+
+// ─── Catalog Provider ────────────────────────────────────────────────────────
+
+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>;
+}
+
+// ─── Main SDK interface ──────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── Plugin Manifest (forgeportal-plugin.json) ───────────────────────────────
+
+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[];   // relative path prefixes
+    actionProviders?:   string[];   // action IDs
+    catalogProviders?:  string[];   // provider IDs
+  };
+}
+
+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>;
+  };
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir":         "dist",
+    "rootDir":        "src",
+    "jsx":            "react-jsx",
+    "declaration":    true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals:     true,
+    include:     ['__tests__/**/*.test.ts', '__tests__/**/*.test-d.ts'],
+  },
+});