@forgeportal/plugin-sdk 1.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @forgeportal/plugin-sdk@1.0.0 build /home/runner/work/forgeportal/forgeportal/packages/plugin-sdk
+> tsc
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bendaamerahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @forgeportal/plugin-sdk
+
+The official SDK for building ForgePortal plugins.
+
+## Installation
+
+```bash
+pnpm add @forgeportal/plugin-sdk
+# For UI plugins also install peer deps:
+pnpm add react @tanstack/react-query
+```
+
+## Plugin Types
+
+| Type        | What it provides                                    |
+|-------------|-----------------------------------------------------|
+| `ui`        | Entity tabs, entity cards, top-level routes         |
+| `backend`   | Fastify routes, action providers, catalog providers |
+| `fullstack` | Both UI and backend capabilities                    |
+
+## Quick Start — UI Plugin
+
+```typescript
+// src/index.ts
+import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { MyEntityTab } from './MyEntityTab.js';
+
+export function registerPlugin(sdk: ForgePluginSDK) {
+  sdk.registerEntityTab({
+    id:        'my-plugin-tab',
+    title:     'My Plugin',
+    component: MyEntityTab,
+    appliesTo: { kinds: ['service'] },
+  });
+}
+```
+
+```typescript
+// src/MyEntityTab.tsx
+import { useEntity } from '@forgeportal/plugin-sdk/react';
+
+export function MyEntityTab() {
+  const { entity } = useEntity();
+  return <div>Entity: {entity.name}</div>;
+}
+```
+
+## Quick Start — Backend Plugin (Action Provider)
+
+```typescript
+// src/actions/myAction.ts
+import type { ActionProvider } from '@forgeportal/plugin-sdk';
+
+export const myAction: ActionProvider = {
+  id:      'myplugin.doSomething',
+  version: 'v1',
+  schema: {
+    input: {
+      type: 'object',
+      properties: { message: { type: 'string', title: 'Message' } },
+      required: ['message'],
+    },
+  },
+  async handler(ctx, input) {
+    ctx.logger.info('Running action', { input });
+    await ctx.log('info', `Processing: ${input['message']}`);
+    return { status: 'success', outputs: { done: true } };
+  },
+};
+```
+
+## Quick Start — Fullstack Plugin (Catalog Provider)
+
+```typescript
+// src/index.ts
+import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { myAction }         from './actions/myAction.js';
+import { MyCatalogTab }     from './MyCatalogTab.js';
+import { myCatalogProvider } from './catalog.js';
+
+export function registerPlugin(sdk: ForgePluginSDK) {
+  // Backend: action provider
+  sdk.registerActionProvider(myAction);
+  // Backend: catalog ingest provider
+  sdk.registerCatalogProvider(myCatalogProvider);
+  // UI: custom entity tab
+  sdk.registerEntityTab({
+    id:        'my-catalog-tab',
+    title:     'My Catalog',
+    component: MyCatalogTab,
+  });
+}
+```
+
+## React Hooks
+
+| Hook              | Description                                                            |
+|-------------------|------------------------------------------------------------------------|
+| `useEntity()`     | Returns `{ entity }` — the current catalog entity. Use inside EntityTab/EntityCard. |
+| `useConfig<T>(key)` | Returns plugin config value from `forgeportal.yaml`.               |
+| `useApi<T>(path)` | TanStack Query wrapper for ForgePortal API calls.                      |
+
+```typescript
+import { useEntity, useConfig, useApi } from '@forgeportal/plugin-sdk/react';
+
+function MyTab() {
+  const { entity }   = useEntity();
+  const apiUrl       = useConfig<string>('apiEndpoint');
+  const { data }     = useApi<{ incidents: unknown[] }>(`/api/v1/my-plugin/${entity.id}/incidents`);
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+## Plugin Manifest (`forgeportal-plugin.json`)
+
+```json
+{
+  "name": "@myorg/forge-plugin-my-plugin",
+  "version": "1.0.0",
+  "forgeportal": {
+    "engineVersion": "^1.0.0",
+    "type": "ui",
+    "capabilities": {
+      "ui": {
+        "entityTabs": ["my-plugin-tab"]
+      }
+    },
+    "config": {
+      "apiEndpoint": {
+        "type": "string",
+        "description": "External service URL",
+        "required": true
+      }
+    }
+  }
+}
+```
+
+## ActionContext Services
+
+| Property           | Type                    | Description                                         |
+|--------------------|-------------------------|-----------------------------------------------------|
+| `config`           | `ActionConfigAccessor`  | Plugin config from `forgeportal.yaml`               |
+| `logger`           | `ActionLogger`          | Structured logger (info/warn/error)                 |
+| `scm`              | `ActionScmAccessor`     | SCM file reads (getFile, listFiles)                 |
+| `db`               | `ActionDbAccessor`      | Read-only SQL query access                          |
+| `acquireRepoLock`  | `(repoUrl) => Promise`  | Advisory lock to prevent concurrent SCM writes      |
+| `log`              | `(level, msg) => Promise` | Persisted action run log line                     |
+
+## Versioning
+
+The SDK follows semantic versioning:
+
+- **Patch** — bug fixes, no interface changes
+- **Minor** — new capabilities (backward-compatible)
+- **Major** — breaking contract changes
+
+Plugins declare `engineVersion: "^1.0.0"` to stay compatible with any 1.x SDK release.
+
+The current SDK version is exported as `SDK_VERSION`:
+
+```typescript
+import { SDK_VERSION } from '@forgeportal/plugin-sdk';
+console.log(SDK_VERSION); // "1.0.0"
+```

package/__tests__/registry.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PluginRegistry } from '../src/registry.js';
+import type { EntityTab, EntityCard, Route, ActionProvider, CatalogProvider } from '../src/types.js';
+
+// ─── Test fixtures ─────────────────────────────────────────────────────────
+
+function makeTab(id: string, kinds?: string[]): EntityTab {
+  return {
+    id,
+    title:     `Tab ${id}`,
+    component: () => null,
+    appliesTo: kinds ? { kinds } : undefined,
+  };
+}
+
+function makeCard(id: string, kinds?: string[]): EntityCard {
+  return {
+    id,
+    title:     `Card ${id}`,
+    component: () => null,
+    appliesTo: kinds ? { kinds } : undefined,
+  };
+}
+
+function makeRoute(path: string, navLabel?: string): Route {
+  return { path, component: () => null, navLabel };
+}
+
+function makeActionProvider(id: string, version = 'v1'): ActionProvider {
+  return {
+    id,
+    version,
+    schema:  { input: { type: 'object', properties: {} } },
+    handler: vi.fn().mockResolvedValue({ status: 'success', outputs: {} }),
+  };
+}
+
+function makeCatalogProvider(id: string): CatalogProvider {
+  return {
+    id,
+    async *ingest() { /* yields nothing */ },
+  };
+}
+
+// ─── EntityTab tests ────────────────────────────────────────────────────────
+
+describe('PluginRegistry — EntityTab', () => {
+  it('registers a tab and retrieves it', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityTab(makeTab('tab-a'));
+    expect(reg.getEntityTabs()).toHaveLength(1);
+    expect(reg.getEntityTabs()[0]?.id).toBe('tab-a');
+  });
+
+  it('skips duplicate registration (warns)', () => {
+    const reg = new PluginRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    reg.registerEntityTab(makeTab('tab-dup'));
+    reg.registerEntityTab(makeTab('tab-dup'));
+    expect(reg.getEntityTabs()).toHaveLength(1);
+    expect(warnSpy).toHaveBeenCalledOnce();
+    warnSpy.mockRestore();
+  });
+
+  it('filters tabs by entity kind — matching kind', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityTab(makeTab('tab-svc', ['service']));
+    reg.registerEntityTab(makeTab('tab-all'));           // no kinds = all
+    const tabs = reg.getEntityTabs('service');
+    expect(tabs.map(t => t.id)).toEqual(['tab-svc', 'tab-all']);
+  });
+
+  it('filters tabs by entity kind — non-matching kind', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityTab(makeTab('tab-svc', ['service']));
+    reg.registerEntityTab(makeTab('tab-all'));
+    const tabs = reg.getEntityTabs('library');
+    expect(tabs.map(t => t.id)).toEqual(['tab-all']);
+  });
+
+  it('returns all tabs when no kind filter provided', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityTab(makeTab('a', ['service']));
+    reg.registerEntityTab(makeTab('b', ['library']));
+    expect(reg.getEntityTabs()).toHaveLength(2);
+  });
+});
+
+// ─── EntityCard tests ───────────────────────────────────────────────────────
+
+describe('PluginRegistry — EntityCard', () => {
+  it('registers and retrieves a card', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityCard(makeCard('card-a'));
+    expect(reg.getEntityCards()).toHaveLength(1);
+  });
+
+  it('skips duplicate cards', () => {
+    const reg = new PluginRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    reg.registerEntityCard(makeCard('card-dup'));
+    reg.registerEntityCard(makeCard('card-dup'));
+    expect(reg.getEntityCards()).toHaveLength(1);
+    warnSpy.mockRestore();
+  });
+
+  it('filters cards by entity kind', () => {
+    const reg = new PluginRegistry();
+    reg.registerEntityCard(makeCard('c-svc', ['service']));
+    reg.registerEntityCard(makeCard('c-all'));
+    expect(reg.getEntityCards('library').map(c => c.id)).toEqual(['c-all']);
+    expect(reg.getEntityCards('service').map(c => c.id)).toEqual(['c-svc', 'c-all']);
+  });
+});
+
+// ─── Route tests ────────────────────────────────────────────────────────────
+
+describe('PluginRegistry — Route', () => {
+  it('registers routes and retrieves them', () => {
+    const reg = new PluginRegistry();
+    reg.registerRoute(makeRoute('/pd', 'PagerDuty'));
+    reg.registerRoute(makeRoute('/slack'));
+    const routes = reg.getRoutes();
+    expect(routes).toHaveLength(2);
+    expect(routes[0]?.navLabel).toBe('PagerDuty');
+    expect(routes[1]?.navLabel).toBeUndefined();
+  });
+
+  it('skips duplicate routes by path', () => {
+    const reg = new PluginRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    reg.registerRoute(makeRoute('/pd'));
+    reg.registerRoute(makeRoute('/pd'));
+    expect(reg.getRoutes()).toHaveLength(1);
+    warnSpy.mockRestore();
+  });
+});
+
+// ─── ActionProvider tests ────────────────────────────────────────────────────
+
+describe('PluginRegistry — ActionProvider', () => {
+  it('registers action providers by id@version key', () => {
+    const reg = new PluginRegistry();
+    reg.registerActionProvider(makeActionProvider('slack.send', 'v1'));
+    reg.registerActionProvider(makeActionProvider('slack.send', 'v2'));
+    expect(reg.getActionProviders()).toHaveLength(2);
+  });
+
+  it('retrieves a specific action provider by id and version', () => {
+    const reg = new PluginRegistry();
+    const provider = makeActionProvider('pd.create', 'v1');
+    reg.registerActionProvider(provider);
+    expect(reg.getActionProvider('pd.create', 'v1')).toBe(provider);
+    expect(reg.getActionProvider('pd.create', 'v2')).toBeUndefined();
+  });
+
+  it('skips duplicate id@version', () => {
+    const reg = new PluginRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    reg.registerActionProvider(makeActionProvider('x', 'v1'));
+    reg.registerActionProvider(makeActionProvider('x', 'v1'));
+    expect(reg.getActionProviders()).toHaveLength(1);
+    warnSpy.mockRestore();
+  });
+});
+
+// ─── CatalogProvider tests ────────────────────────────────────────────────────
+
+describe('PluginRegistry — CatalogProvider', () => {
+  it('registers catalog providers', () => {
+    const reg = new PluginRegistry();
+    reg.registerCatalogProvider(makeCatalogProvider('pd-catalog'));
+    expect(reg.getCatalogProviders()).toHaveLength(1);
+  });
+
+  it('skips duplicate catalog provider IDs', () => {
+    const reg = new PluginRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    reg.registerCatalogProvider(makeCatalogProvider('dup'));
+    reg.registerCatalogProvider(makeCatalogProvider('dup'));
+    expect(reg.getCatalogProviders()).toHaveLength(1);
+    warnSpy.mockRestore();
+  });
+});
+
+// ─── Registry isolation ───────────────────────────────────────────────────────
+
+describe('PluginRegistry — isolation', () => {
+  it('two registry instances do not share state', () => {
+    const a = new PluginRegistry();
+    const b = new PluginRegistry();
+    a.registerEntityTab(makeTab('shared-tab'));
+    expect(b.getEntityTabs()).toHaveLength(0);
+  });
+});

package/__tests__/types.test-d.ts

@@ -0,0 +1,60 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import type {
+  ForgePluginSDK,
+  ActionProvider,
+  ActionContext,
+  ActionResult,
+  PluginManifest,
+} from '../src/types.js';
+
+describe('ForgePluginSDK interface', () => {
+  it('has all registration methods', () => {
+    type Methods = keyof ForgePluginSDK;
+    expectTypeOf<'registerEntityTab'>().toMatchTypeOf<Methods>();
+    expectTypeOf<'registerEntityCard'>().toMatchTypeOf<Methods>();
+    expectTypeOf<'registerRoute'>().toMatchTypeOf<Methods>();
+    expectTypeOf<'registerActionProvider'>().toMatchTypeOf<Methods>();
+    expectTypeOf<'registerCatalogProvider'>().toMatchTypeOf<Methods>();
+  });
+});
+
+describe('ActionResult interface', () => {
+  it('requires status and outputs', () => {
+    type Keys = keyof ActionResult;
+    expectTypeOf<'status'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'outputs'>().toMatchTypeOf<Keys>();
+  });
+
+  it('status is a union of success | failed', () => {
+    expectTypeOf<ActionResult['status']>().toEqualTypeOf<'success' | 'failed'>();
+  });
+});
+
+describe('ActionContext interface', () => {
+  it('exposes all required service accessors', () => {
+    type Keys = keyof ActionContext;
+    expectTypeOf<'config'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'logger'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'scm'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'db'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'acquireRepoLock'>().toMatchTypeOf<Keys>();
+    expectTypeOf<'log'>().toMatchTypeOf<Keys>();
+  });
+
+  it('acquireRepoLock takes a string and returns Promise<void>', () => {
+    expectTypeOf<ActionContext['acquireRepoLock']>().toEqualTypeOf<(repoUrl: string) => Promise<void>>();
+  });
+});
+
+describe('PluginManifest interface', () => {
+  it('forgeportal.type is a union of plugin types', () => {
+    expectTypeOf<PluginManifest['forgeportal']['type']>().toEqualTypeOf<'ui' | 'backend' | 'fullstack'>();
+  });
+});
+
+describe('ActionProvider interface', () => {
+  it('handler returns Promise<ActionResult>', () => {
+    type HandlerReturn = ReturnType<ActionProvider['handler']>;
+    expectTypeOf<HandlerReturn>().toEqualTypeOf<Promise<ActionResult>>();
+  });
+});

package/dist/backend.d.ts

@@ -0,0 +1,56 @@
+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 declare class BackendPluginRegistry implements ForgeBackendPluginSDK {
+    readonly config: ActionConfigAccessor;
+    readonly logger: ActionLogger;
+    private readonly _actionProviders;
+    private readonly _catalogProviders;
+    private readonly _routes;
+    constructor(config: ActionConfigAccessor, logger: ActionLogger);
+    registerActionProvider(provider: ActionProvider): void;
+    registerCatalogProvider(provider: CatalogProvider): void;
+    registerBackendRoute(route: BackendRoute): void;
+    getActionProviders(): ActionProvider[];
+    getCatalogProviders(): CatalogProvider[];
+    getBackendRoutes(): BackendRoute[];
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,IAAI,EAAK,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,4EAA4E;IAC5E,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACvD,6EAA6E;IAC7E,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACzD;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IAM/D,QAAQ,CAAC,MAAM,EAAE,oBAAoB;IACrC,QAAQ,CAAC,MAAM,EAAE,YAAY;IAN/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IACxE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAGnC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,YAAY;IAG/B,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAStD,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAQxD,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAI/C,kBAAkB,IAAK,cAAc,EAAE;IACvC,mBAAmB,IAAI,eAAe,EAAE;IACxC,gBAAgB,IAAO,YAAY,EAAE;CACtC"}

package/dist/backend.js

@@ -0,0 +1,37 @@
+/**
+ * Backend plugin registry — in-memory store for backend capabilities.
+ * Instantiated by the plugin loader for each plugin.
+ */
+export class BackendPluginRegistry {
+    config;
+    logger;
+    _actionProviders = new Map();
+    _catalogProviders = new Map();
+    _routes = [];
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    registerActionProvider(provider) {
+        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) {
+        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) {
+        this._routes.push(route);
+    }
+    getActionProviders() { return [...this._actionProviders.values()]; }
+    getCatalogProviders() { return [...this._catalogProviders.values()]; }
+    getBackendRoutes() { return [...this._routes]; }
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AA6CA;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IAMrB;IACA;IANM,gBAAgB,GAAI,IAAI,GAAG,EAA0B,CAAC;IACtD,iBAAiB,GAAG,IAAI,GAAG,EAA2B,CAAC;IACvD,OAAO,GAAmB,EAAE,CAAC;IAE9C,YACW,MAA4B,EAC5B,MAAoB;QADpB,WAAM,GAAN,MAAM,CAAsB;QAC5B,WAAM,GAAN,MAAM,CAAc;IAC5B,CAAC;IAEJ,sBAAsB,CAAC,QAAwB;QAC7C,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACjD,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,qCAAqC,GAAG,kCAAkC,CAAC,CAAC;YACzF,OAAO;QACT,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,uBAAuB,CAAC,QAAyB;QAC/C,IAAI,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,sCAAsC,QAAQ,CAAC,EAAE,kCAAkC,CAAC,CAAC;YAClG,OAAO;QACT,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,oBAAoB,CAAC,KAAmB;QACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,kBAAkB,KAAyB,OAAO,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxF,mBAAmB,KAAwB,OAAO,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACzF,gBAAgB,KAA2B,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACvE"}

package/dist/context.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { Entity } from './types.js';
+interface EntityContextValue {
+    entity: Entity;
+}
+export declare const EntityContext: React.Context<EntityContextValue | null>;
+export declare function EntityProvider({ entity, children, }: {
+    entity: Entity;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+interface PluginConfigContextValue {
+    get<T = unknown>(key: string): T | undefined;
+}
+export declare const PluginConfigContext: React.Context<PluginConfigContextValue>;
+export declare function PluginConfigProvider({ config, children, }: {
+    config: Record<string, unknown>;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** @internal Used by useEntity hook */
+export declare function useEntityContext(): EntityContextValue | null;
+/** @internal Used by useConfig hook */
+export declare function usePluginConfigContext(): PluginConfigContextValue;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoC,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIzC,UAAU,kBAAkB;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,aAAa,0CAAiD,CAAC;AAE5E,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,QAAQ,GACT,EAAE;IACD,MAAM,EAAI,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,2CAMA;AAID,UAAU,wBAAwB;IAChC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC9C;AAMD,eAAO,MAAM,mBAAmB,yCAAyD,CAAC;AAE1F,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,QAAQ,GACT,EAAE;IACD,MAAM,EAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,2CASA;AAED,uCAAuC;AACvC,wBAAgB,gBAAgB,IAAI,kBAAkB,GAAG,IAAI,CAE5D;AAED,uCAAuC;AACvC,wBAAgB,sBAAsB,IAAI,wBAAwB,CAEjE"}

package/dist/context.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+export const EntityContext = createContext(null);
+export function EntityProvider({ entity, children, }) {
+    return (_jsx(EntityContext.Provider, { value: { entity }, children: children }));
+}
+const defaultConfig = {
+    get: () => undefined,
+};
+export const PluginConfigContext = createContext(defaultConfig);
+export function PluginConfigProvider({ config, children, }) {
+    const accessor = {
+        get: (key) => config[key],
+    };
+    return (_jsx(PluginConfigContext.Provider, { value: accessor, children: children }));
+}
+/** @internal Used by useEntity hook */
+export function useEntityContext() {
+    return useContext(EntityContext);
+}
+/** @internal Used by useConfig hook */
+export function usePluginConfigContext() {
+    return useContext(PluginConfigContext);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AASzD,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAA4B,IAAI,CAAC,CAAC;AAE5E,MAAM,UAAU,cAAc,CAAC,EAC7B,MAAM,EACN,QAAQ,GAIT;IACC,OAAO,CACL,KAAC,aAAa,CAAC,QAAQ,IAAC,KAAK,EAAE,EAAE,MAAM,EAAE,YACtC,QAAQ,GACc,CAC1B,CAAC;AACJ,CAAC;AAQD,MAAM,aAAa,GAA6B;IAC9C,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;CACrB,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;AAE1F,MAAM,UAAU,oBAAoB,CAAC,EACnC,MAAM,EACN,QAAQ,GAIT;IACC,MAAM,QAAQ,GAA6B;QACzC,GAAG,EAAE,CAAc,GAAW,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAkB;KAChE,CAAC;IACF,OAAO,CACL,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAQ,YAC1C,QAAQ,GACoB,CAChC,CAAC;AACJ,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAC,aAAa,CAAC,CAAC;AACnC,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,sBAAsB;IACpC,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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';
+export { PluginRegistry, globalRegistry } from './registry.js';
+export type { BackendRoute, ForgeBackendPluginSDK } from './backend.js';
+export { BackendPluginRegistry } from './backend.js';
+export declare const SDK_VERSION = "1.0.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,MAAM,EACN,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,KAAK,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/D,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// ─── Registry ─────────────────────────────────────────────────────────────────
+export { PluginRegistry, globalRegistry } from './registry.js';
+export { BackendPluginRegistry } from './backend.js';
+// ─── SDK version (used by plugin loader for engineVersion compatibility check) ─
+export const SDK_VERSION = '1.0.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,iFAAiF;AACjF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,kFAAkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,32 @@
+import { type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import type { Entity } from './types.js';
+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 declare function useEntity(): {
+    entity: Entity;
+};
+/**
+ * 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 declare function useConfig<T = unknown>(key: string): T | undefined;
+/**
+ * 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 declare function useApi<TData = unknown>(path: string, options?: Omit<UseQueryOptions<TData>, 'queryKey' | 'queryFn'>): UseQueryResult<TData, Error>;
+//# sourceMappingURL=react.d.ts.map