@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/Stopper.ts

@@ -0,0 +1,29 @@
+const serviceId = "hookup.to/service/stopper";
+const serviceName = "Stopper";
+
+class Stopper {
+  uuid: string;
+  board: any;
+  app: any;
+
+  constructor(app: any, board: any, _descriptor: any, id: string) {
+    this.uuid = id;
+    this.board = board;
+    this.app = app;
+  }
+
+  configure(_config: any): void {}
+
+  process(_params: any): null {
+    return null;
+  }
+}
+
+const descriptor = {
+  serviceName,
+  serviceId,
+  create: (app: any, board: any, descriptor: any, id: string) =>
+    new Stopper(app, board, descriptor, id),
+};
+
+export default descriptor;

package/bundle/hkp-frontend/src/runtime/browser/services/Switch.tsx

@@ -0,0 +1,419 @@
+import {
+  AppImpl,
+  ProcessContext,
+  RuntimeClassType,
+  ServiceClass,
+} from "hkp-frontend/src/types";
+import { nestedRun } from "hkp-frontend/src/runtime/processContext";
+import ServiceBase from "./ServiceBase";
+import SwitchUI from "./SwitchUI";
+import BrowserRegistry from "../BrowserRegistry";
+import BrowserRuntimeScope from "../BrowserRuntimeScope";
+import { addService, configureService } from "../BrowserRuntimeApi";
+import { joinAddress, splitAddress } from "../../board/address";
+import {
+  parseExpression,
+  evalExpression,
+  Expression,
+  SyntaxError,
+} from "./base/eval";
+
+/**
+ * Service Documentation
+ * Service ID: hookup.to/service/switch
+ * Service Name: Switch
+ * Modes: case routing
+ * Key Config: cases ([{ when: <expression on params>, pipeline: [services] }]),
+ *             default (pipeline run when no case matches),
+ *             ignoreInnerResult
+ * Input: any
+ * Output: the matched case's pipeline result; pass-through when no case
+ *         matches and no default pipeline is configured
+ * Arrays: routed as a whole (predicates see the full array as params)
+ * Binary: routed untouched
+ * MixedData: not native in browser runtime
+ *
+ * The structured if/else of the browser runtime: the first case whose `when`
+ * expression is truthy routes the input through its sub-pipeline. Conditions
+ * are jsep expressions over { params } — e.g. "params.next",
+ * "params.kind == 'audio'". An empty matched pipeline passes the input
+ * through unchanged.
+ *
+ * A case is a branch of the pipeline the Switch sits in, not a scope of its
+ * own: its services hold values in the slots of whatever holds the Switch,
+ * report what they do outward under `<switch>.<instanceId>`, and are reached
+ * by that address — so an instanceId must be unique across all the cases.
+ */
+
+const serviceId = "hookup.to/service/switch";
+const serviceName = "Switch";
+
+type PipelineEntry = {
+  serviceId: string;
+  instanceId: string;
+  serviceName?: string;
+  state?: Record<string, any>;
+};
+
+type SwitchCase = {
+  when: string;
+  pipeline: PipelineEntry[];
+};
+
+type State = {
+  cases: SwitchCase[];
+  default: PipelineEntry[];
+  ignoreInnerResult?: boolean;
+};
+
+function normalizePipeline(pipeline: any): PipelineEntry[] {
+  if (!Array.isArray(pipeline)) {
+    return [];
+  }
+  return pipeline.map((entry: any) => ({
+    serviceId: entry.serviceId,
+    instanceId: entry.instanceId || crypto.randomUUID(),
+    ...(entry.serviceName ? { serviceName: entry.serviceName } : {}),
+    ...(entry.state ? { state: entry.state } : {}),
+  }));
+}
+
+class Switch extends ServiceBase<State> {
+  private _parsedConditions: Array<Expression | SyntaxError | null> = [];
+  // One scope per case, plus the default pipeline's scope at the last index.
+  private _scopes: Array<BrowserRuntimeScope | null> = [];
+  private _scopesBuilding: Promise<void> | null = null;
+  private _scopeGeneration = 0;
+
+  constructor(app: AppImpl, board: string, descriptor: ServiceClass, id: string) {
+    super(app, board, descriptor, id, {
+      cases: [],
+      default: [],
+    });
+  }
+
+  configure(config: any): void {
+    // Branch-scoped ops (from SubServicePipelineUI inside SwitchUI):
+    // { branch: <case index> | "default", appendService | removeService |
+    //   pipeline | configureService | when }
+    if (config.branch !== undefined) {
+      this._configureBranch(config);
+      return;
+    }
+
+    let rebuildNeeded = false;
+
+    if (Array.isArray(config.cases)) {
+      this.state.cases = config.cases.map((c: any) => ({
+        when: typeof c.when === "string" ? c.when : "",
+        pipeline: normalizePipeline(c.pipeline),
+      }));
+      this._parsedConditions = this.state.cases.map((c) =>
+        c.when ? parseExpression(c.when) : null,
+      );
+      this.app.notify(this, { cases: this.state.cases });
+      rebuildNeeded = true;
+    }
+
+    if (Array.isArray(config.default)) {
+      this.state.default = normalizePipeline(config.default);
+      this.app.notify(this, { default: this.state.default });
+      rebuildNeeded = true;
+    }
+
+    if (config.ignoreInnerResult !== undefined) {
+      this.state.ignoreInnerResult = config.ignoreInnerResult;
+    }
+
+    if (rebuildNeeded) {
+      this._rebuildScopes();
+    }
+  }
+
+  async process(params: any): Promise<any> {
+    // Before anything is awaited: the run this call is in is only this call's
+    // until it gives up control.
+    const run = this.app.currentContext?.(this);
+    for (let i = 0; i < this.state.cases.length; i++) {
+      const condition = this._parsedConditions[i];
+      if (condition === null || condition === "syntax-error") {
+        continue;
+      }
+      const met = await evalExpression(condition, { params }, this.app, this);
+      if (met) {
+        this.app.notify(this, { matched: i });
+        return this._runPipeline(i, this.state.cases[i].pipeline, params, run);
+      }
+    }
+
+    if (this.state.default.length > 0) {
+      this.app.notify(this, { matched: "default" });
+      return this._runPipeline(
+        this.state.cases.length,
+        this.state.default,
+        params,
+        run,
+      );
+    }
+    this.app.notify(this, { matched: null });
+    return params;
+  }
+
+  destroy(): void {
+    this._teardownScopes();
+  }
+
+  /** Ends every pass running inside any case; see BrowserRuntimeScope. */
+  cancelInFlight(): void {
+    for (const scope of this._scopes) {
+      scope?.cancelInFlight();
+    }
+  }
+
+  /**
+   * Whether the cases' pipelines have been built, so that what runs inside
+   * them can be found — and listened to — by its scoped address.
+   */
+  isScopeBuilt(): boolean {
+    const pipelines = [
+      ...this.state.cases.map((c) => c.pipeline),
+      this.state.default,
+    ];
+    return (
+      pipelines.every((pipeline) => pipeline.length === 0) ||
+      this._scopes.length === pipelines.length
+    );
+  }
+
+  /** The service a scoped address names inside one of the cases, however deep. */
+  findNested(address: string): any {
+    const segments = splitAddress(address);
+    if (segments.length === 0) {
+      return null;
+    }
+    const here = this.getInnerInstance(segments[0]);
+    if (!here || segments.length === 1) {
+      return segments.length === 1 ? here : null;
+    }
+    return typeof here.findNested === "function"
+      ? here.findNested(segments.slice(1).join("."))
+      : null;
+  }
+
+  getInnerInstance(instanceId: string): any {
+    for (const scope of this._scopes) {
+      const svc = scope?.findServiceInstance(instanceId)[0];
+      if (svc) {
+        return svc;
+      }
+    }
+    return null;
+  }
+
+  // ── Internals ──────────────────────────────────────────────────────────────
+
+  private _branchPipeline(branch: number | "default"): PipelineEntry[] | null {
+    if (branch === "default") {
+      return this.state.default;
+    }
+    return this.state.cases[branch]?.pipeline ?? null;
+  }
+
+  private _setBranchPipeline(
+    branch: number | "default",
+    pipeline: PipelineEntry[],
+  ): void {
+    if (branch === "default") {
+      this.state.default = pipeline;
+      this.app.notify(this, { default: this.state.default });
+    } else {
+      this.state.cases = this.state.cases.map((c, i) =>
+        i === branch ? { ...c, pipeline } : c,
+      );
+      this.app.notify(this, { cases: this.state.cases });
+    }
+  }
+
+  private _configureBranch(config: any): void {
+    const branch: number | "default" =
+      config.branch === "default" ? "default" : Number(config.branch);
+    const current = this._branchPipeline(branch);
+    if (current === null) {
+      return;
+    }
+
+    if (typeof config.when === "string" && branch !== "default") {
+      this.state.cases = this.state.cases.map((c, i) =>
+        i === branch ? { ...c, when: config.when } : c,
+      );
+      this._parsedConditions[branch] = config.when
+        ? parseExpression(config.when)
+        : null;
+      this.app.notify(this, { cases: this.state.cases });
+    }
+
+    if (Array.isArray(config.pipeline)) {
+      this._setBranchPipeline(branch, normalizePipeline(config.pipeline));
+      this._rebuildScopes();
+    } else if (config.appendService) {
+      this._setBranchPipeline(branch, [
+        ...current,
+        ...normalizePipeline([config.appendService]),
+      ]);
+      this._rebuildScopes();
+    } else if (typeof config.removeService === "string") {
+      this._setBranchPipeline(
+        branch,
+        current.filter((e) => e.instanceId !== config.removeService),
+      );
+      this._rebuildScopes();
+    } else if (config.configureService) {
+      const { instanceId, state } = config.configureService;
+      const live = this.getInnerInstance(instanceId);
+      if (live?.configure) {
+        live.configure(state);
+        Promise.resolve(
+          live.getConfiguration ? live.getConfiguration() : live.state,
+        ).then((updatedState: any) => {
+          this._setBranchPipeline(
+            branch,
+            current.map((e) =>
+              e.instanceId === instanceId ? { ...e, state: updatedState } : e,
+            ),
+          );
+        });
+      } else {
+        this._setBranchPipeline(
+          branch,
+          current.map((e) =>
+            e.instanceId === instanceId
+              ? { ...e, state: { ...e.state, ...state } }
+              : e,
+          ),
+        );
+      }
+    }
+  }
+
+  private async _runPipeline(
+    index: number,
+    pipeline: PipelineEntry[],
+    params: any,
+    run: ProcessContext | undefined,
+  ): Promise<any> {
+    if (pipeline.length === 0) {
+      return params;
+    }
+    if (!this._scopes[index]) {
+      await this._scopesBuilding;
+    }
+    const scope = this._scopes[index];
+    if (!scope) {
+      return params;
+    }
+    // Answered by returning, so not reported through onResult as well.
+    const result = await scope.next(null, params, nestedRun(run), false, false);
+    return this.state.ignoreInnerResult ? params : result;
+  }
+
+  private _teardownScopes(): void {
+    // Ends what runs inside, not only the references: see dispose.
+    this._scopes.forEach((scope) => void scope?.dispose());
+    this._scopes = [];
+    this._scopesBuilding = null;
+    this._scopeGeneration++;
+  }
+
+  private _rebuildScopes(): void {
+    const generation = ++this._scopeGeneration;
+    this._scopes.forEach((scope) => void scope?.dispose());
+    this._scopes = [];
+
+    const pipelines = [
+      ...this.state.cases.map((c) => c.pipeline),
+      this.state.default,
+    ];
+
+    this._scopesBuilding = (async () => {
+      const scopes: Array<BrowserRuntimeScope | null> = [];
+      for (const pipeline of pipelines) {
+        scopes.push(pipeline.length > 0 ? await this._buildScope(pipeline) : null);
+      }
+      if (generation !== this._scopeGeneration) {
+        scopes.forEach((scope) => void scope?.dispose());
+        return;
+      }
+      this._scopes = scopes;
+      this.app.notify(this, { __innerScopesReady: true });
+    })();
+  }
+
+  private async _buildScope(pipeline: PipelineEntry[]): Promise<BrowserRuntimeScope> {
+    const registry = new BrowserRegistry();
+    const scope = new BrowserRuntimeScope(
+      {
+        id: `switch-inner-${this.uuid}-${crypto.randomUUID()}`,
+        name: "Switch Pipeline",
+        type: "browser" as RuntimeClassType,
+      },
+      registry,
+    );
+    // The board's assets, as the runtime around this pipeline sees them.
+    scope.assets = () => this.app.assets?.() ?? [];
+    // And whoever is signed in to the app around it is signed in here.
+    scope.delegateIdentity(() => this.app.getAuthenticatedUser?.() ?? null);
+
+    // Propagate runtime variables up through the scope hierarchy
+    scope.app.getRuntimeVariable = () => this.app.getRuntimeVariable();
+    scope.app.setRuntimeVariable = (key: string, value: any) =>
+      this.app.setRuntimeVariable(key, value);
+
+    // A branch sees the cells around the Switch, as the pipeline it branches
+    // from does. Delegated before any service is added, so one that holds a
+    // value while being configured holds it there.
+    scope.delegateSlots(() => this.app.slots?.() ?? null);
+
+    // What happens inside a case is reported outward under the address
+    // through this Switch, as a sub-service reports its pipeline — which is
+    // what lets a panel or the overview outside see it.
+    const outerNotify = this.app.notify.bind(this.app);
+    const innerNotify = scope.app.notify.bind(scope.app);
+    scope.app.notify = (svc: any, notification: any) => {
+      innerNotify(svc, notification);
+      // A scope being let go of says nothing more outside; see dispose.
+      if (scope.isDisposing) {
+        return;
+      }
+      outerNotify(
+        { ...svc, address: joinAddress(this.uuid, svc.address ?? svc.uuid) },
+        notification,
+      );
+    };
+
+    for (const entry of pipeline) {
+      const descriptor = await addService(
+        scope,
+        {
+          serviceId: entry.serviceId,
+          serviceName: entry.serviceName ?? entry.serviceId,
+        },
+        entry.instanceId,
+      );
+      if (descriptor && entry.state) {
+        await configureService(scope, descriptor, entry.state);
+      }
+    }
+
+    return scope;
+  }
+}
+
+const descriptor = {
+  serviceName,
+  serviceId,
+  create: (app: AppImpl, board: string, descriptor: ServiceClass, id: string) =>
+    new Switch(app, board, descriptor, id),
+  createUI: SwitchUI,
+};
+
+export default descriptor;

package/bundle/hkp-frontend/src/runtime/browser/services/SwitchUI.tsx

@@ -0,0 +1,171 @@
+import { useCallback, useState } from "react";
+import { ServiceInstance, ServiceUIProps } from "hkp-frontend/src/types";
+import ServiceUI from "hkp-frontend/src/ui-components/service/ServiceUI";
+import InputField from "hkp-frontend/src/components/shared/InputField";
+import SubServicePipelineUI from "../../ui/SubServicePipelineUI";
+import { findServiceUI } from "../UIRegistry";
+
+type PipelineEntry = {
+  serviceId: string;
+  instanceId: string;
+  serviceName?: string;
+  state?: any;
+};
+
+type SwitchCase = {
+  when: string;
+  pipeline: PipelineEntry[];
+};
+
+// Matches the `matched` notification payload: case index, "default", or null
+// when the input passed through unrouted.
+type MatchedBranch = number | "default" | null;
+
+type BranchKey = number | "default";
+
+function ActiveDot({ isActive }: { isActive: boolean }) {
+  return (
+    <span
+      style={{
+        display: "inline-block",
+        width: 6,
+        height: 6,
+        borderRadius: "50%",
+        flexShrink: 0,
+        background: isActive ? "var(--hkp-accent)" : "transparent",
+        border: isActive ? "none" : "1px solid hsl(var(--border))",
+      }}
+    />
+  );
+}
+
+export default function SwitchUI(props: ServiceUIProps) {
+  const [cases, setCases] = useState<SwitchCase[]>([]);
+  const [defaultPipeline, setDefaultPipeline] = useState<PipelineEntry[]>([]);
+  const [matched, setMatched] = useState<MatchedBranch | undefined>(undefined);
+  const [, setScopeVersion] = useState(0);
+
+  const onInit = (initialState: any) => {
+    if (Array.isArray(initialState?.cases)) {
+      setCases(initialState.cases);
+    }
+    if (Array.isArray(initialState?.default)) {
+      setDefaultPipeline(initialState.default);
+    }
+  };
+
+  const onNotification = useCallback((notification: any) => {
+    if (Array.isArray(notification?.cases)) {
+      setCases(notification.cases);
+    }
+    if (Array.isArray(notification?.default)) {
+      setDefaultPipeline(notification.default);
+    }
+    if ("matched" in (notification || {})) {
+      setMatched(notification.matched);
+    }
+    if (notification?.__innerScopesReady) {
+      setScopeVersion((v) => v + 1);
+    }
+  }, []);
+
+  const getActualInstance = useCallback(
+    (instanceId: string): ServiceInstance | null => {
+      const svc = props.service as any;
+      return svc.getInnerInstance?.(instanceId) ?? null;
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [props.service],
+  );
+
+  const { service } = props;
+
+  // Facade the branch as a service whose `pipeline` state and configure()
+  // speak SubServicePipelineUI's protocol, translated into branch-scoped
+  // configure calls on the Switch.
+  const branchProxy = (
+    branch: BranchKey,
+    label: string,
+    pipeline: PipelineEntry[],
+  ): ServiceInstance =>
+    ({
+      uuid: `${service.uuid}-branch-${branch}`,
+      // A branch is not a service: what runs in it reports under the Switch,
+      // so the panels below listen under the Switch's address, not under this
+      // proxy's invented uuid — which names nothing and hears nothing.
+      address: service.address ?? service.uuid,
+      serviceId: "hookup.to/service/switch",
+      serviceName: label,
+      state: { pipeline },
+      app: service.app,
+      board: service.board,
+      configure: async (config: any) =>
+        service.configure({ ...config, branch }),
+      process: async () => {},
+      getConfiguration: async () => ({ pipeline }),
+      destroy: async () => {},
+    }) as unknown as ServiceInstance;
+
+  const renderBranch = (
+    branch: BranchKey,
+    pipeline: PipelineEntry[],
+    isActive: boolean,
+    whenExpression?: string,
+  ) => (
+    <div key={String(branch)} className="flex flex-col gap-1">
+      <div className="flex items-center gap-2 text-xs">
+        <ActiveDot isActive={isActive} />
+        {branch === "default" ? (
+          <span className="font-mono whitespace-nowrap">default</span>
+        ) : (
+          <InputField
+            label=""
+            value={whenExpression ?? ""}
+            onChange={(when) => service.configure({ branch, when })}
+          />
+        )}
+      </div>
+      <div className="pl-4">
+        <SubServicePipelineUI
+          service={branchProxy(
+            branch,
+            branch === "default" ? "Default Pipeline" : `Case ${branch}`,
+            pipeline,
+          )}
+          findServiceUI={findServiceUI}
+          getActualInstance={getActualInstance}
+          defaultCollapsed={true}
+          // The trail names the Switch as well as the branch: which case this
+          // is means nothing without the service it is a case of.
+          levelLabel={`${service.serviceName} · ${
+            branch === "default" ? "default" : `case ${branch}`
+          }`}
+        />
+      </div>
+    </div>
+  );
+
+  return (
+    <ServiceUI
+      {...props}
+      className="pb-2"
+      onInit={onInit}
+      onNotification={onNotification}
+    >
+      <div className="flex flex-col gap-1" style={{ minWidth: 260 }}>
+        {cases.length === 0 && defaultPipeline.length === 0 ? (
+          <div className="text-xs text-neutral-500">
+            No cases configured — passing everything through.
+          </div>
+        ) : (
+          <>
+            {cases.map((c, i) =>
+              renderBranch(i, c.pipeline, matched === i, c.when),
+            )}
+            {renderBranch("default", defaultPipeline, matched === "default")}
+          </>
+        )}
+      </div>
+    </ServiceUI>
+  );
+}