@flowscripter/plugin-api 1.3.2 → 2.0.0

package/README.md

@@ -19,9 +19,20 @@ Add the module:
 Use the module:
 
 ```typescript
-import { world } from "@flowscripter/plugin-api";
-
-world();
+import {
+  createComponentPlugin,
+  type ComponentFactory,
+  type Datastore,
+} from "@flowscripter/plugin-api";
+
+const datastoreFactory: ComponentFactory<unknown, Datastore> = {
+  create: async () => ({
+    config: {},
+    async *getAllDataEntries() {},
+  }),
+};
+
+const plugin = createComponentPlugin({ datastoreFactory });
 ```
 
 ## Development

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { CLIPlugin, CLIPluginOptions, CommandFactory, } from "@flowscripter/dynamic-cli-framework-api";
+export { createCLIPlugin } from "@flowscripter/dynamic-cli-framework-api";
+export type { LogFields, Logger, LogLevel, MetricEvent, Output, ProgressEvent, StructuredValue, } from "./src/host.ts";
+export type { DataCollection, DataEntry, DataModel, Datastore, DatastoreManager, FlowscripterComponent, ProcessingGraph, Registry, RuntimeContext, Session, SessionManager, } from "./src/component.ts";
+export type { ComponentFactory, ComponentPlugin, ComponentPluginOptions, DataModelExtensionDescriptor, DatastoreExtensionDescriptor, RegistryExtensionDescriptor, } from "./src/plugin.ts";
+export { createComponentPlugin, FLOWSCRIPTER_DATA_MODEL, FLOWSCRIPTER_DATASTORE, FLOWSCRIPTER_REGISTRY, } from "./src/plugin.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,GACf,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,YAAY,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,OAAO,EACP,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createCLIPlugin } from "@flowscripter/dynamic-cli-framework-api";
+export { createComponentPlugin, FLOWSCRIPTER_DATA_MODEL, FLOWSCRIPTER_DATASTORE, FLOWSCRIPTER_REGISTRY, } from "./src/plugin.js";

package/dist/src/component.d.ts

@@ -0,0 +1,66 @@
+import type { Logger, MetricEvent, Output, ProgressEvent } from "./host.ts";
+/**
+ * Base for all Flowscripter runtime components. The config is opaque to the runtime and is
+ * validated by the component itself.
+ */
+export interface FlowscripterComponent<TConfig = unknown> {
+    readonly config: TConfig;
+    dispose?(): void | Promise<void>;
+}
+/**
+ * Members to be refined in flowscripter/runtime#10.
+ */
+export interface DataModel extends FlowscripterComponent {
+}
+export interface DataEntry {
+    readonly model: DataModel;
+}
+export interface Datastore extends FlowscripterComponent {
+    getAllDataEntries(): AsyncIterable<DataEntry>;
+}
+/**
+ * Read-only view of the components loaded in a runtime, keyed by handle.
+ */
+export interface Registry {
+    getAllDatastores(): Iterable<[string, Datastore]>;
+    getAllDataModels(): Iterable<[string, DataModel]>;
+}
+export interface DatastoreManager {
+    getAll(): Iterable<[string, Datastore]>;
+}
+export interface DataCollection {
+    getAll(): AsyncIterable<DataEntry>;
+    add(entry: DataEntry): Promise<void>;
+    remove(entry: DataEntry): Promise<boolean>;
+}
+/**
+ * Opaque placeholder; nodes and edges are defined by the ticket which implements processing.
+ */
+export type ProcessingGraph = unknown;
+/**
+ * Mutable during a run: the host and components add and remove entries.
+ */
+export interface Session {
+    readonly graph?: ProcessingGraph;
+    readonly inputs: DataCollection;
+    readonly results: DataCollection;
+}
+export interface SessionManager {
+    getAll(): Iterable<[string, Session]>;
+    create(handle: string): Promise<Session>;
+    remove(handle: string): Promise<boolean>;
+}
+/**
+ * Everything a runtime needs for processing, passed to components on creation.
+ */
+export interface RuntimeContext {
+    readonly logger: Logger;
+    readonly output: Output;
+    reportProgress(event: ProgressEvent): void;
+    reportMetric(event: MetricEvent): void;
+    readonly registry: Registry;
+    readonly datastoreManager: DatastoreManager;
+    readonly sessionManager: SessionManager;
+    readonly session: Session;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/src/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO,GAAG,OAAO;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,qBAAqB;CAAG;AAE3D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,SAAU,SAAQ,qBAAqB;IACtD,iBAAiB,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,gBAAgB,IAAI,QAAQ,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAClD,gBAAgB,IAAI,QAAQ,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,IAAI,QAAQ,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,IAAI,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3C,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B"}

package/dist/src/component.js

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

package/dist/src/host.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Plain structured data (JSON-compatible) which a host may pretty-print and highlight.
+ */
+export type StructuredValue = string | number | boolean | null | ReadonlyArray<StructuredValue> | {
+    readonly [key: string]: StructuredValue;
+};
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export type LogFields = Readonly<Record<string, StructuredValue>>;
+/**
+ * Levelled sink for runtime processing events (diagnostics, not results).
+ */
+export interface Logger {
+    /**
+     * The lazy form must not invoke the callback when debug logging is disabled.
+     */
+    debug(message: string | (() => string), fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    /**
+     * `cause` is passed as-is and may be an `Error` with circular references; implementations render it
+     * with a circular-safe formatter and must not rely on `JSON.stringify` (which gives `{}` for an `Error`).
+     */
+    error(message: string, fields?: LogFields, cause?: unknown): void;
+}
+/**
+ * Sink for the results of runtime processing (distinct from {@link Logger}).
+ */
+export interface Output {
+    write(value: string | StructuredValue): void;
+}
+export interface ProgressEvent {
+    readonly id: string;
+    readonly operation: string;
+    readonly state: "start" | "update" | "end";
+    readonly current?: number;
+    readonly total?: number;
+    readonly message?: string;
+}
+export interface MetricEvent {
+    readonly name: string;
+    readonly value: number;
+    readonly unit?: string;
+    readonly tags?: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/src/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/host.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,aAAa,CAAC,eAAe,CAAC,GAC9B;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD"}

package/dist/src/host.js

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

package/dist/src/plugin.d.ts

@@ -0,0 +1,53 @@
+import type { ExtensionDescriptor, Plugin } from "@flowscripter/dynamic-plugin-framework";
+import type { DataModel, Datastore, Registry, RuntimeContext } from "./component.ts";
+export declare const FLOWSCRIPTER_DATA_MODEL = "FLOWSCRIPTER_DATA_MODEL";
+export declare const FLOWSCRIPTER_DATASTORE = "FLOWSCRIPTER_DATASTORE";
+export declare const FLOWSCRIPTER_REGISTRY = "FLOWSCRIPTER_REGISTRY";
+/**
+ * Returned by the framework extension factory. The runtime resolves the config (starting from
+ * `defaultConfig`) and then calls `create` itself, so rich services bypass the string-only
+ * framework `hostData`.
+ */
+export interface ComponentFactory<TConfig, TComponent> {
+    readonly defaultConfig?: TConfig;
+    create(context: RuntimeContext, config: TConfig): Promise<TComponent>;
+}
+export interface DataModelExtensionDescriptor extends ExtensionDescriptor {
+    readonly extensionPoint: typeof FLOWSCRIPTER_DATA_MODEL;
+    readonly factory: {
+        create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, DataModel>>;
+    };
+}
+export interface DatastoreExtensionDescriptor extends ExtensionDescriptor {
+    readonly extensionPoint: typeof FLOWSCRIPTER_DATASTORE;
+    readonly factory: {
+        create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, Datastore>>;
+    };
+}
+export interface RegistryExtensionDescriptor extends ExtensionDescriptor {
+    readonly extensionPoint: typeof FLOWSCRIPTER_REGISTRY;
+    readonly factory: {
+        create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, Registry>>;
+    };
+}
+/**
+ * A {@link Plugin} whose extension descriptors are limited to the Flowscripter component
+ * extension points.
+ */
+export interface ComponentPlugin extends Plugin {
+    readonly extensionDescriptors: ReadonlyArray<DataModelExtensionDescriptor | DatastoreExtensionDescriptor | RegistryExtensionDescriptor>;
+}
+type FactoryOrProvider<T> = T | (() => Promise<T>);
+export interface ComponentPluginOptions {
+    readonly dataModelFactory?: FactoryOrProvider<ComponentFactory<unknown, DataModel>>;
+    readonly datastoreFactory?: FactoryOrProvider<ComponentFactory<unknown, Datastore>>;
+    readonly registryFactory?: FactoryOrProvider<ComponentFactory<unknown, Registry>>;
+    readonly pluginData?: ReadonlyMap<string, string>;
+}
+/**
+ * Build a {@link ComponentPlugin} from component factories (or factory functions), without
+ * needing to hand-construct extension descriptors.
+ */
+export declare function createComponentPlugin(options: ComponentPluginOptions): ComponentPlugin;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/src/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErF,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AACjE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,EAAE,UAAU;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,uBAAuB,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE;QAChB,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;KACvF,CAAC;CACH;AAED,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,sBAAsB,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE;QAChB,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;KACvF,CAAC;CACH;AAED,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE,QAAQ,CAAC,cAAc,EAAE,OAAO,qBAAqB,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE;QAChB,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;KACtF,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,MAAM;IAC7C,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAC1C,4BAA4B,GAAG,4BAA4B,GAAG,2BAA2B,CAC1F,CAAC;CACH;AAED,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACpF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnD;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAwBtF"}

package/dist/src/plugin.js

@@ -0,0 +1,33 @@
+export const FLOWSCRIPTER_DATA_MODEL = "FLOWSCRIPTER_DATA_MODEL";
+export const FLOWSCRIPTER_DATASTORE = "FLOWSCRIPTER_DATASTORE";
+export const FLOWSCRIPTER_REGISTRY = "FLOWSCRIPTER_REGISTRY";
+async function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+/**
+ * Build a {@link ComponentPlugin} from component factories (or factory functions), without
+ * needing to hand-construct extension descriptors.
+ */
+export function createComponentPlugin(options) {
+    const extensionDescriptors = [];
+    const { dataModelFactory, datastoreFactory, registryFactory } = options;
+    if (dataModelFactory) {
+        extensionDescriptors.push({
+            extensionPoint: FLOWSCRIPTER_DATA_MODEL,
+            factory: { create: () => resolve(dataModelFactory) },
+        });
+    }
+    if (datastoreFactory) {
+        extensionDescriptors.push({
+            extensionPoint: FLOWSCRIPTER_DATASTORE,
+            factory: { create: () => resolve(datastoreFactory) },
+        });
+    }
+    if (registryFactory) {
+        extensionDescriptors.push({
+            extensionPoint: FLOWSCRIPTER_REGISTRY,
+            factory: { create: () => resolve(registryFactory) },
+        });
+    }
+    return { extensionDescriptors, pluginData: options.pluginData };
+}

package/index.ts

@@ -1 +1,42 @@
-export * from "./src/world.ts";
+export type {
+  CLIPlugin,
+  CLIPluginOptions,
+  CommandFactory,
+} from "@flowscripter/dynamic-cli-framework-api";
+export { createCLIPlugin } from "@flowscripter/dynamic-cli-framework-api";
+export type {
+  LogFields,
+  Logger,
+  LogLevel,
+  MetricEvent,
+  Output,
+  ProgressEvent,
+  StructuredValue,
+} from "./src/host.ts";
+export type {
+  DataCollection,
+  DataEntry,
+  DataModel,
+  Datastore,
+  DatastoreManager,
+  FlowscripterComponent,
+  ProcessingGraph,
+  Registry,
+  RuntimeContext,
+  Session,
+  SessionManager,
+} from "./src/component.ts";
+export type {
+  ComponentFactory,
+  ComponentPlugin,
+  ComponentPluginOptions,
+  DataModelExtensionDescriptor,
+  DatastoreExtensionDescriptor,
+  RegistryExtensionDescriptor,
+} from "./src/plugin.ts";
+export {
+  createComponentPlugin,
+  FLOWSCRIPTER_DATA_MODEL,
+  FLOWSCRIPTER_DATASTORE,
+  FLOWSCRIPTER_REGISTRY,
+} from "./src/plugin.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/plugin-api",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "description": "Flowscripter plugin API: interfaces for command and component plugins",
   "keywords": [
     "api",
@@ -30,7 +30,8 @@
       "bun": "./index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
@@ -38,13 +39,17 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json"
   },
+  "dependencies": {
+    "@flowscripter/dynamic-cli-framework-api": "^5.1.1",
+    "@flowscripter/dynamic-plugin-framework": "^2.3.2"
+  },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "oxfmt": "0.57.0",
-    "oxlint": "1.72.0"
+    "@types/bun": "^1.4.3",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0"
   },
   "peerDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "typedocOptions": {
     "readme": "none",

package/src/component.ts

@@ -0,0 +1,75 @@
+import type { Logger, MetricEvent, Output, ProgressEvent } from "./host.ts";
+
+/**
+ * Base for all Flowscripter runtime components. The config is opaque to the runtime and is
+ * validated by the component itself.
+ */
+export interface FlowscripterComponent<TConfig = unknown> {
+  readonly config: TConfig;
+  dispose?(): void | Promise<void>;
+}
+
+/**
+ * Members to be refined in flowscripter/runtime#10.
+ */
+export interface DataModel extends FlowscripterComponent {}
+
+export interface DataEntry {
+  readonly model: DataModel;
+}
+
+export interface Datastore extends FlowscripterComponent {
+  getAllDataEntries(): AsyncIterable<DataEntry>;
+}
+
+/**
+ * Read-only view of the components loaded in a runtime, keyed by handle.
+ */
+export interface Registry {
+  getAllDatastores(): Iterable<[string, Datastore]>;
+  getAllDataModels(): Iterable<[string, DataModel]>;
+}
+
+export interface DatastoreManager {
+  getAll(): Iterable<[string, Datastore]>;
+}
+
+export interface DataCollection {
+  getAll(): AsyncIterable<DataEntry>;
+  add(entry: DataEntry): Promise<void>;
+  remove(entry: DataEntry): Promise<boolean>;
+}
+
+/**
+ * Opaque placeholder; nodes and edges are defined by the ticket which implements processing.
+ */
+export type ProcessingGraph = unknown;
+
+/**
+ * Mutable during a run: the host and components add and remove entries.
+ */
+export interface Session {
+  readonly graph?: ProcessingGraph;
+  readonly inputs: DataCollection;
+  readonly results: DataCollection;
+}
+
+export interface SessionManager {
+  getAll(): Iterable<[string, Session]>;
+  create(handle: string): Promise<Session>;
+  remove(handle: string): Promise<boolean>;
+}
+
+/**
+ * Everything a runtime needs for processing, passed to components on creation.
+ */
+export interface RuntimeContext {
+  readonly logger: Logger;
+  readonly output: Output;
+  reportProgress(event: ProgressEvent): void;
+  reportMetric(event: MetricEvent): void;
+  readonly registry: Registry;
+  readonly datastoreManager: DatastoreManager;
+  readonly sessionManager: SessionManager;
+  readonly session: Session;
+}

package/src/host.ts

@@ -0,0 +1,54 @@
+/**
+ * Plain structured data (JSON-compatible) which a host may pretty-print and highlight.
+ */
+export type StructuredValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ReadonlyArray<StructuredValue>
+  | { readonly [key: string]: StructuredValue };
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+export type LogFields = Readonly<Record<string, StructuredValue>>;
+
+/**
+ * Levelled sink for runtime processing events (diagnostics, not results).
+ */
+export interface Logger {
+  /**
+   * The lazy form must not invoke the callback when debug logging is disabled.
+   */
+  debug(message: string | (() => string), fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  /**
+   * `cause` is passed as-is and may be an `Error` with circular references; implementations render it
+   * with a circular-safe formatter and must not rely on `JSON.stringify` (which gives `{}` for an `Error`).
+   */
+  error(message: string, fields?: LogFields, cause?: unknown): void;
+}
+
+/**
+ * Sink for the results of runtime processing (distinct from {@link Logger}).
+ */
+export interface Output {
+  write(value: string | StructuredValue): void;
+}
+
+export interface ProgressEvent {
+  readonly id: string;
+  readonly operation: string;
+  readonly state: "start" | "update" | "end";
+  readonly current?: number;
+  readonly total?: number;
+  readonly message?: string;
+}
+
+export interface MetricEvent {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly tags?: Readonly<Record<string, string>>;
+}

package/src/plugin.ts

@@ -0,0 +1,90 @@
+import type { ExtensionDescriptor, Plugin } from "@flowscripter/dynamic-plugin-framework";
+import type { DataModel, Datastore, Registry, RuntimeContext } from "./component.ts";
+
+export const FLOWSCRIPTER_DATA_MODEL = "FLOWSCRIPTER_DATA_MODEL";
+export const FLOWSCRIPTER_DATASTORE = "FLOWSCRIPTER_DATASTORE";
+export const FLOWSCRIPTER_REGISTRY = "FLOWSCRIPTER_REGISTRY";
+
+/**
+ * Returned by the framework extension factory. The runtime resolves the config (starting from
+ * `defaultConfig`) and then calls `create` itself, so rich services bypass the string-only
+ * framework `hostData`.
+ */
+export interface ComponentFactory<TConfig, TComponent> {
+  readonly defaultConfig?: TConfig;
+  create(context: RuntimeContext, config: TConfig): Promise<TComponent>;
+}
+
+export interface DataModelExtensionDescriptor extends ExtensionDescriptor {
+  readonly extensionPoint: typeof FLOWSCRIPTER_DATA_MODEL;
+  readonly factory: {
+    create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, DataModel>>;
+  };
+}
+
+export interface DatastoreExtensionDescriptor extends ExtensionDescriptor {
+  readonly extensionPoint: typeof FLOWSCRIPTER_DATASTORE;
+  readonly factory: {
+    create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, Datastore>>;
+  };
+}
+
+export interface RegistryExtensionDescriptor extends ExtensionDescriptor {
+  readonly extensionPoint: typeof FLOWSCRIPTER_REGISTRY;
+  readonly factory: {
+    create(hostData?: Map<string, string>): Promise<ComponentFactory<unknown, Registry>>;
+  };
+}
+
+/**
+ * A {@link Plugin} whose extension descriptors are limited to the Flowscripter component
+ * extension points.
+ */
+export interface ComponentPlugin extends Plugin {
+  readonly extensionDescriptors: ReadonlyArray<
+    DataModelExtensionDescriptor | DatastoreExtensionDescriptor | RegistryExtensionDescriptor
+  >;
+}
+
+type FactoryOrProvider<T> = T | (() => Promise<T>);
+
+export interface ComponentPluginOptions {
+  readonly dataModelFactory?: FactoryOrProvider<ComponentFactory<unknown, DataModel>>;
+  readonly datastoreFactory?: FactoryOrProvider<ComponentFactory<unknown, Datastore>>;
+  readonly registryFactory?: FactoryOrProvider<ComponentFactory<unknown, Registry>>;
+  readonly pluginData?: ReadonlyMap<string, string>;
+}
+
+async function resolve<T extends object>(value: FactoryOrProvider<T>): Promise<T> {
+  return typeof value === "function" ? (value as () => Promise<T>)() : value;
+}
+
+/**
+ * Build a {@link ComponentPlugin} from component factories (or factory functions), without
+ * needing to hand-construct extension descriptors.
+ */
+export function createComponentPlugin(options: ComponentPluginOptions): ComponentPlugin {
+  const extensionDescriptors: ComponentPlugin["extensionDescriptors"][number][] = [];
+  const { dataModelFactory, datastoreFactory, registryFactory } = options;
+
+  if (dataModelFactory) {
+    extensionDescriptors.push({
+      extensionPoint: FLOWSCRIPTER_DATA_MODEL,
+      factory: { create: () => resolve(dataModelFactory) },
+    });
+  }
+  if (datastoreFactory) {
+    extensionDescriptors.push({
+      extensionPoint: FLOWSCRIPTER_DATASTORE,
+      factory: { create: () => resolve(datastoreFactory) },
+    });
+  }
+  if (registryFactory) {
+    extensionDescriptors.push({
+      extensionPoint: FLOWSCRIPTER_REGISTRY,
+      factory: { create: () => resolve(registryFactory) },
+    });
+  }
+
+  return { extensionDescriptors, pluginData: options.pluginData };
+}

package/src/world.ts

@@ -1,6 +0,0 @@
-/**
- * Logs out `World`.
- */
-export function world(): void {
-  console.info("World");
-}