@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/pluginBase.ts

@@ -0,0 +1,248 @@
+/**
+ * Plugin Base Types and Classes
+ *
+ * These are copied from @unoverse-platform/plugin-base to remove the
+ * compile-time dependency. This allows node-service to start without
+ * packages/ being mounted.
+ *
+ * SINCE 2026-07-29 THIS IS THE ONLY IN-REPO COPY: the plugin-base source retired to
+ * _legacy/plugin-base once the last code node (postgres-toolkit) did, and everything
+ * in-repo that still speaks the plugin protocol — packages/marketplace, the server's
+ * component runtime — imports from here. The PUBLISHED @unoverse-platform/plugin-base
+ * stays on npm, frozen, for externally installed plugins; the loader still names it by
+ * that string.
+ *
+ * A FAITHFUL transcription, including its loosest part: plugin-base's own index exported
+ * `export type EnhancedNodeDefinition = any` (and friends) as LOCAL declarations, which
+ * SHADOW its `export * from "./types"` star export — so every consumer's "typed" imports
+ * were `any` all along. The aliases below reproduce that, rather than pretending the old
+ * package gave marketplace type-safety it never had.
+ */
+
+/**
+ * Platform dependencies for internal use
+ */
+export interface PlatformDependencies {
+  PromiseNode: any;
+  CallbackNode: any;
+  NodeInputType: any;
+  NodeConcurrency: any;
+  getNodeCredentials: (context: any, credentialName: string) => Promise<any>;
+  getConfig: () => any;
+  createLogger: (name: string) => any;
+  saveTokenUsage: (usage: any) => Promise<void>;
+  callService: (method: string, params: any, context: any) => Promise<any>;
+  getRedisClient: () => any;
+  gravityPublish: (channel: string, message: any) => Promise<void>;
+  executeNodeWithRouting?: (
+    executeNode: (inputs: any, config: any, context: any) => Promise<any>,
+    params: any,
+    config: any,
+    context: any
+  ) => Promise<any>;
+  deliverToNode?: (
+    executionId: string,
+    nodeId: string,
+    handle: string,
+    value: unknown,
+    signal?: string,
+  ) => Promise<void>;
+  getAudioWebSocketManager?: () => any;
+  [key: string]: any;
+}
+
+/**
+ * Base class for Promise-based nodes
+ */
+export class PromiseNode {
+  nodeType: string;
+  logger: any = { info: () => {}, error: () => {}, debug: () => {} };
+
+  constructor(name: string) {
+    this.nodeType = name || "stub";
+  }
+
+  protected async validateConfig(config: any): Promise<any> {
+    return { success: true };
+  }
+
+  protected async executeNode(inputs: any, config: any, context: any): Promise<any> {
+    return {};
+  }
+
+  protected validateAndGetContext(context: any) {
+    return {
+      workflowId: context?.workflowId || context?.workflow?.id || "",
+      executionId: context?.executionId || context?.workflow?.runId || "",
+      nodeId: context?.nodeId || "",
+    };
+  }
+
+  protected getExecutionContext(context: any) {
+    return {
+      workflowId: context?.workflowId || context?.workflow?.id || "",
+      executionId: context?.executionId || context?.workflow?.runId || "",
+      nodeId: context?.nodeId || "",
+      nodeType: context?.nodeType || this.nodeType || "",
+      config: context?.config || {},
+      credentials: context?.credentials || {},
+    };
+  }
+
+  async execute(inputs: any, config: any, context: any): Promise<any> {
+    return this.executeNode(inputs, config, context);
+  }
+}
+
+/**
+ * Base class for Callback-based nodes
+ */
+export class CallbackNode {
+  constructor(name: string) {}
+}
+
+/**
+ * Node input type enum
+ */
+export const NodeInputType = {
+  STRING: "string",
+  OBJECT: "object",
+  ARRAY: "array",
+  NUMBER: "number",
+  BOOLEAN: "boolean",
+};
+
+// Global platform instance
+let platformDeps: PlatformDependencies | null = null;
+
+/**
+ * Set platform dependencies (called by plugin setup)
+ */
+export function setPlatformDependencies(deps: PlatformDependencies) {
+  if (platformDeps !== null) {
+    return;
+  }
+  platformDeps = deps;
+}
+
+/** The loose compile-time aliases plugin-base actually exported (see the header). */
+export type EnhancedNodeDefinition = any;
+export type ValidationResult = any;
+export type NodeExecutionContext = any;
+
+/** Plugin interface that packages implement. Transcribed from plugin-base index.ts. */
+export interface GravityPlugin {
+  name: string;
+  version?: string;
+  description?: string;
+  setup(api: GravityPluginAPI): void | Promise<void>;
+}
+
+/** The API the platform hands a plugin's setup(). Transcribed from plugin-base index.ts. */
+export interface GravityPluginAPI {
+  registerNode(node: PluginNodeDefinition): void;
+  registerService(name: string, service: any): void;
+  registerCredential(credential: any): void;
+  registerComponentPath?(packagePath: string): void;
+  createLogger(name: string): any;
+  getConfig(): any;
+  saveTokenUsage(usage: any): Promise<void>;
+  saveMCPTrace(trace: any): Promise<string>;
+  getNodeCredentials(context: any, credentialName: string): Promise<any>;
+  callService(method: string, params: any, context: any): Promise<any>;
+  getRedisClient(): any;
+  gravityPublish(channel: string, message: any): Promise<void>;
+  getAudioWebSocketManager?: () => any;
+  getWebSocketManager?: () => any;
+  publishStreamingUpdate?: (config: { componentType: string; props: Record<string, any> }) => void;
+  executeNodeWithRouting?: (
+    executeNode: (inputs: any, config: any, context: any) => Promise<any>,
+    params: any,
+    config: any,
+    context: any,
+  ) => Promise<any>;
+  deliverToNode?: (
+    executionId: string,
+    nodeId: string,
+    handle: string,
+    value: unknown,
+    signal?: string,
+  ) => Promise<void>;
+  classes: { PromiseNode: any; CallbackNode: any };
+  types: { NodeInputType: any; NodeConcurrency: any };
+}
+
+export interface PluginNodeDefinition {
+  definition: any;
+  executor: any;
+}
+
+/** Helper to create a plugin — the identity function plugin-base always was. */
+export function createPlugin(config: {
+  name: string;
+  version?: string;
+  description?: string;
+  setup: (api: GravityPluginAPI) => void | Promise<void>;
+}): GravityPlugin {
+  return config;
+}
+
+/**
+ * Initialize platform dependencies from the plugin API — transcribed from plugin-base
+ * index.ts, the same field mapping, so a plugin moving its import here behaves
+ * identically at setup time.
+ */
+export function initializePlatformFromAPI(api: GravityPluginAPI) {
+  setPlatformDependencies({
+    PromiseNode: api.classes.PromiseNode,
+    CallbackNode: api.classes.CallbackNode,
+    NodeInputType: api.types.NodeInputType,
+    NodeConcurrency: api.types.NodeConcurrency,
+    getNodeCredentials: api.getNodeCredentials,
+    getConfig: api.getConfig,
+    createLogger: api.createLogger,
+    saveTokenUsage: api.saveTokenUsage,
+    saveMCPTrace: api.saveMCPTrace,
+    callService: api.callService,
+    getRedisClient: api.getRedisClient,
+    gravityPublish: api.gravityPublish,
+    executeNodeWithRouting: api.executeNodeWithRouting,
+    deliverToNode: api.deliverToNode,
+    getAudioWebSocketManager: api.getAudioWebSocketManager,
+  } as PlatformDependencies);
+}
+
+// The prop-key reader marketplace's synthesizer uses — base's own copy, re-exported so a
+// plugin needs ONE import root here rather than knowing base's internal layout.
+export { inputPropKeys, type InputPropLike } from "./definitions/inputs.js";
+
+/**
+ * Get platform dependencies
+ */
+export function getPlatformDependencies(): PlatformDependencies {
+  if (!platformDeps) {
+    return {
+      packageVersion: "1.1.1",
+      PromiseNode,
+      CallbackNode,
+      NodeInputType,
+      NodeConcurrency: {},
+      getConfig: () => ({}),
+      createLogger: () => ({ info: () => {}, error: () => {}, debug: () => {}, warn: () => {} }),
+      saveTokenUsage: () => Promise.resolve(),
+      saveMCPTrace: () => Promise.resolve(),
+      callService: () => Promise.resolve(null),
+      getRedisClient: () => null,
+      gravityPublish: async () => {},
+      executeNodeWithRouting: async () => ({}),
+      getAudioWebSocketManager: () => null,
+      getNodeCredentials: async (context: any, credentialName: string) => {
+        if (platformDeps?.getNodeCredentials) {
+          return platformDeps.getNodeCredentials(context, credentialName);
+        }
+        return context?.credentials?.[credentialName] || {};
+      },
+    } as any;
+  }
+  return platformDeps;
+}

package/vendor/base/src/plugins/README.md

@@ -0,0 +1,57 @@
+# plugins/ — LEGACY. Nothing new goes here.
+
+This folder loads **JavaScript** nodes: a package with a `src/`, a `setup(api)` call, and
+classes extending `PromiseNode` or `CallbackNode`. Every node becomes a YAML manifest
+(`../manifests/`), so this whole folder is scheduled for deletion.
+
+**Do not add to it. Do not tidy it. Do not move it.** Work spent here is work spent twice.
+
+## What is still holding it open
+
+17 packages still ship `src/`. Most are vendor integrations and are pure migration work,
+but three are platform capability and are why this cannot simply be switched off:
+
+| Package | Why it matters |
+|---|---|
+| `flow` | `IfElse`, `LoopStart`, `LoopEnd`, `Code`, `Context`, `FieldValidator`. **Control flow.** Deleting this folder today breaks every workflow with a loop or a condition |
+| `ingest` | the content pipeline (document parsing, sheets, connectors) |
+| `spatial` | `SpatialSearch` |
+
+Two of the remaining ones also need the executor to grow first
+(`DECLARATIVE_NODES.md` §10): a socket transport with audio framing for `openai-realtime`
+and the streaming half of `elevenlabs`, and catalog matching for the hubspot and salesforce
+attribute pull. Everything else is conversion, not invention.
+
+## The folder is two jobs, dying on two timelines
+
+```
+discovery.ts  loader.ts  redis.ts  state.ts   ← code-node loading. Dies with the last src/ package
+```
+
+**The npm half is GONE.** `install.ts` and `startup.ts` are deleted, and with them
+`CORE_PACKAGES` — the boot step that installed `@unoverse-platform/marketplace` so the
+design system could resolve out of that package. `013_items.sql` said where it was going:
+"Installing something from the marketplace is an INSERT... no npm, no image, no rsync, no
+restart." Rows replaced npm for content exactly as manifests replaced code for nodes, and
+MARKETPLACE.md §5 is now the whole story — a universe fetches from the marketplace URL at
+install time and writes a row.
+
+The last traces went with it (2026-08-30): `apps/unoverse` no longer declares
+`@unoverse-platform/marketplace` as a dependency (nothing ever imported it — the only
+mention was a string label), and `definitions/registry/homes.ts` no longer lists the
+`PLUGINS_DIR/node_modules/...` bundle as a candidate. The core platform has no
+relationship with the marketplace package at all; it talks to the marketplace over HTTP.
+
+What remains here is one job, not two: loading code nodes.
+
+## How it ends
+
+No flag day. Each package that converts to YAML removes one reason for this folder to exist.
+When no package ships `src/`, delete `discovery.ts`, `loader.ts`, `redis.ts` and
+`../pluginBase.ts`. When installs are rows, delete the rest and the folder with it.
+
+The two Vite warnings a developer sees when starting Studio come from `discovery.ts` and
+`loader.ts` (dynamic `import()` of a package by name). They are correct, they are
+unfixable while this folder exists, and they leave when it does.
+
+See `docs/architecture/DECLARATIVE_NODES.md` §7a and §10.

package/vendor/base/src/plugins/discovery.ts

@@ -0,0 +1,87 @@
+/**
+ * Plugin Discovery — finds plugins from /packages folder
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { PluginMetadata } from "../types.js";
+import { PACKAGES_PATH, PLUGINS_DIR, NODES_HOME } from "../paths.js";
+
+let ALL_PLUGINS: string[] = [];
+
+export function getAllPlugins(): string[] {
+  return ALL_PLUGINS;
+}
+
+export function setAllPlugins(plugins: string[]): void {
+  ALL_PLUGINS = plugins;
+}
+
+/** Scan a directory for plugin packages (a package.json whose name is in `scopes` and has an entry). */
+function scanPluginDir(dir: string, scopes: string[]): string[] {
+  const plugins: string[] = [];
+  if (!fs.existsSync(dir)) return plugins;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const pkgJsonPath = path.join(dir, entry.name, "package.json");
+    if (!fs.existsSync(pkgJsonPath)) continue;
+    try {
+      const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+      const pkgName = pkgJson.name;
+      if (!pkgName || pkgName.includes("/docs")) continue;
+      if (scopes.some((s) => pkgName.startsWith(s)) && (pkgJson.main || pkgJson.exports)) {
+        plugins.push(pkgName);
+      }
+    } catch {
+      // Skip invalid package.json files
+    }
+  }
+  return plugins;
+}
+
+/** Nodes that have been moved INTO Unoverse (apps/unoverse/nodes). */
+export function discoverNodesHome(): string[] {
+  return scanPluginDir(NODES_HOME, ["@unoverse-platform/"]);
+}
+
+/**
+ * LEGACY starter-kit packages. The fallback from before nodes moved to `nodes/`.
+ *
+ * Absent is the NORMAL state now, so its absence is not worth a line at boot. It used to
+ * warn, which was right when the folder was expected and missing meant something was wrong.
+ */
+export function discoverPlugins(): string[] {
+  return scanPluginDir(PACKAGES_PATH, ["@unoverse-platform/"]);
+}
+
+export async function getPluginMetadata(pluginName: string): Promise<PluginMetadata> {
+  try {
+    const packagesPath = PACKAGES_PATH;
+    const shortName = pluginName.replace("@unoverse-platform/", "");
+    const pkgJsonPath = path.join(packagesPath, shortName, "package.json");
+
+    const pluginsDir = PLUGINS_DIR;
+    const npmPkgJsonPath = path.join(pluginsDir, "node_modules", pluginName, "package.json");
+
+    let pkg: any;
+    if (fs.existsSync(pkgJsonPath)) {
+      pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    } else if (fs.existsSync(npmPkgJsonPath)) {
+      pkg = JSON.parse(fs.readFileSync(npmPkgJsonPath, "utf-8"));
+    } else {
+      pkg = await import(/* @vite-ignore */ `${pluginName}/package.json`);
+    }
+
+    const gravity = pkg.gravity || {};
+    return {
+      version: pkg.version || "1.0.0",
+      description: pkg.description || "",
+      category: gravity.category || undefined,
+      displayName: gravity.displayName || undefined,
+      features: gravity.features || undefined,
+      credentials: gravity.credentials || undefined,
+    };
+  } catch {
+    return { version: "1.0.0", description: "" };
+  }
+}

package/vendor/base/src/plugins/index.ts

@@ -0,0 +1,16 @@
+export { getPluginState, setPluginState, isPluginEnabled, persistPluginState, removePluginState, listPluginState } from "./state.js";
+export { getAllPlugins, getPluginMetadata, discoverPlugins } from "./discovery.js";
+export { loadPlugin, unloadPlugin } from "./loader.js";
+/**
+ * NO INSTALL EXPORT, DELIBERATELY. `install.ts` held `installPlugin`/`uninstallPlugin`,
+ * which shelled out to `npm install` at runtime and imported whatever came back, gated by
+ * an `@unoverse-platform` scope allowlist. That whole lane is retired (MARKETPLACE.md §10
+ * q3, removed 2026-08-30): a universe takes content from the marketplace as ROWS via
+ * `POST /marketplace/install`, and node packages are declarative YAML already on the box.
+ * Nothing fetches or executes code from a package registry any more.
+ */
+export { warnMissingNodeMeta } from "./redis.js";
+// startup.ts (loadInstalledNpmPlugins) retired 2026-08-06: it survived the npm-plugin
+// plane only as the bridge that loaded @unoverse-platform/marketplace's duplicate of the
+// Component-node executor. The server registers the node from its own code
+// (runtime/components/registerComponentNode); the package is content only.

package/vendor/base/src/plugins/loader.ts

@@ -0,0 +1,179 @@
+/**
+ * Plugin Loader — loads plugins and registers nodes into the in-memory registry.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { pathToFileURL } from "url";
+import { getNodeRegistry, getPluginNodeMap, deleteNode } from "../registry.js";
+import { PACKAGES_PATH, MARKETPLACE_PATH, PLUGINS_DIR, NODES_HOME } from "../paths.js";
+
+/**
+ * Resolve a package directory's entry file from its package.json.
+ *
+ * CommonJS `require(dir)` reads package.json "main" and loads it; ESM `import(dir)`
+ * does NOT do directory/main resolution for a filesystem path (it only does so for
+ * bare package specifiers). Since the engine moved to ESM we resolve the entry
+ * ourselves — supporting `exports["."]` and `main`, falling back to index.js.
+ */
+function resolveEntry(dir: string): string {
+  // Unoverse runs under tsx in BOTH dev and prod (see Dockerfile), so it can import a
+  // package's TypeScript source directly. For the in-Unoverse node packages (NODES_HOME),
+  // prefer `src/index.ts` when it exists: this sidesteps the whole "stale/missing dist"
+  // failure class — most painfully the `components` package, which is regenerated by
+  // `nodegen:local` and whose gitignored dist silently goes missing (the runtime then
+  // boots without those nodes and the workflow pulls a partial catalog → "Unknown node
+  // type: CardFinder"). Loading from src also means a regenerated node takes effect on
+  // restart with no separate build. Scoped to NODES_HOME so legacy /packages and
+  // marketplace plugins keep their existing (bundled-dist) resolution untouched.
+  if (path.resolve(dir).startsWith(path.resolve(NODES_HOME) + path.sep)) {
+    const srcTs = path.join(dir, "src", "index.ts");
+    if (fs.existsSync(srcTs)) return srcTs;
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+  let entry: string = pkg.main || "index.js";
+  const exp = pkg.exports;
+  if (exp) {
+    const dot = typeof exp === "string" ? exp : exp["."] ?? exp;
+    if (typeof dot === "string") entry = dot;
+    else if (dot && typeof dot === "object") entry = dot.import || dot.require || dot.default || entry;
+  }
+  return path.join(dir, entry);
+}
+
+/**
+ * Import a plugin from a directory (resolving its entry file as a file:// URL) or,
+ * if no local directory exists, from its bare package specifier (npm-resolved).
+ */
+export async function importPluginModule(dirOrName: string): Promise<any> {
+  let hasPkg = false;
+  try {
+    hasPkg = fs.existsSync(path.join(dirOrName, "package.json"));
+  } catch {
+    hasPkg = false;
+  }
+  // @vite-ignore: loading a plugin by name IS the job here, so the specifier cannot be
+  // static. Vite is right to warn and there is nothing to fix while this folder exists;
+  // the warning printed on every Studio start (see ./README.md, this folder is legacy).
+  const target = hasPkg ? pathToFileURL(resolveEntry(dirOrName)).href : dirOrName;
+  return import(/* @vite-ignore */ target);
+}
+
+/**
+ * Clear all cached modules under a given path so re-import loads fresh code.
+ *
+ * Under ESM there is no `require.cache`, and `import()` caches by URL with no
+ * public API to evict — so plugin hot-reload is a no-op here and is handled by
+ * a process restart instead (see the marketplace upgrade docs). Guarded so the
+ * call site stays identical to the CJS original.
+ */
+export function clearModuleCache(modulePath: string): void {
+  const req = (globalThis as { require?: { cache?: Record<string, unknown> } }).require;
+  if (!req?.cache) return;
+  const resolved = path.resolve(modulePath);
+  for (const key of Object.keys(req.cache)) {
+    if (key.startsWith(resolved)) {
+      delete req.cache[key];
+    }
+  }
+}
+
+export async function loadPlugin(pluginName: string, api: any): Promise<string[]> {
+  const nodeRegistry = getNodeRegistry();
+  const nodeTypes: string[] = [];
+  const nodesBefore = new Set(nodeRegistry.keys());
+
+  try {
+    const shortName = pluginName.replace(/@[^/]+\//, "");
+    // Resolution order: the in-Unoverse node home wins, then legacy /packages,
+    // then /packages-marketplace, then the bare npm specifier.
+    const homePath = path.join(NODES_HOME, shortName);
+    const pkgPath = path.join(PACKAGES_PATH, shortName);
+    const mktPath = path.join(MARKETPLACE_PATH, shortName);
+    const resolvedPath = fs.existsSync(homePath)
+      ? homePath
+      : fs.existsSync(pkgPath)
+        ? pkgPath
+        : fs.existsSync(mktPath)
+          ? mktPath
+          : pluginName;
+
+    const pkg = await importPluginModule(resolvedPath);
+    const plugin = pkg.default || pkg;
+
+    if (plugin && typeof plugin.setup === "function") {
+      await plugin.setup(api);
+
+      for (const [type] of nodeRegistry) {
+        if (!nodesBefore.has(type)) {
+          nodeTypes.push(type);
+        }
+      }
+
+      // Stamp package-level marketplace metadata (package.json `gravity`) onto the nodes
+      // this plugin just registered. By the authoring convention (packages/docs/nodes), a
+      // package's icon lives in `gravity.logoUrl` and applies to every node in the package
+      // — it is NOT repeated on each createNodeDefinition(). node-service merged this; the
+      // Unoverse runtime didn't, so the Canvas drew these nodes with no icon. A node that
+      // sets its own logoUrl wins; the package value is only a fallback.
+      try {
+        const pkgJsonPath = path.join(resolvedPath, "package.json");
+        if (fs.existsSync(pkgJsonPath)) {
+          const gravity = (JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8")).gravity ?? {}) as {
+            logoUrl?: string;
+          };
+          if (gravity.logoUrl) {
+            for (const type of nodeTypes) {
+              const def = nodeRegistry.get(type) as { logoUrl?: string } | undefined;
+              if (def && !def.logoUrl) def.logoUrl = gravity.logoUrl;
+            }
+          }
+        }
+      } catch {
+        // Marketplace metadata is best-effort — a missing/!malformed manifest must not
+        // fail node loading.
+      }
+    }
+  } catch (error: any) {
+    console.log(`  ⚠ Failed to load ${pluginName}: ${error.message}`);
+  }
+
+  return nodeTypes;
+}
+
+export function unloadPlugin(pluginName: string): void {
+  const pluginNodeMap = getPluginNodeMap();
+  const nodeTypes = pluginNodeMap.get(pluginName) || [];
+
+  // Drop from the in-memory registry. Workflow re-pulls the catalog (GET /nodes),
+  // so there is no Redis catalog to purge.
+  for (const nodeType of nodeTypes) {
+    deleteNode(nodeType);
+  }
+
+  pluginNodeMap.delete(pluginName);
+}
+
+export function getPluginsDir(): string {
+  return PLUGINS_DIR;
+}
+
+export function ensurePluginsDir(): void {
+  if (!fs.existsSync(PLUGINS_DIR)) {
+    fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+  }
+  // No seeded dependencies. plugin-base retired 2026-07-29 with the last code node —
+  // an installed package that needs it (an OLD published version) declares it as an
+  // ordinary npm dependency and npm installs it transitively; the self-heal that used
+  // to force-upgrade it existed for PEER-dep node packages, and none remain.
+  const pkgJsonPath = path.join(PLUGINS_DIR, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) {
+    fs.writeFileSync(pkgJsonPath, JSON.stringify({
+      name: "gravity-plugins",
+      private: true,
+      dependencies: {},
+    }, null, 2));
+  }
+}

package/vendor/base/src/plugins/redis.ts

@@ -0,0 +1,36 @@
+/**
+ * Node-meta guard. (Formerly also held the Redis node/credential catalog writers —
+ * removed with the catalog repoint: the catalog now lives in the in-memory registry
+ * and is pulled by workflow over HTTP, so there is nothing to write to Redis.)
+ */
+
+import { boot } from "../boot.js";
+
+/**
+ * Meta sync guard — LOUD signal whenever a batch of node defs is registered.
+ *
+ * `whenToUse` is the field the node ranker (CatalogService / semantic search)
+ * embeds; if it's empty the search silently degrades to name+description. A stale
+ * build or a freshly imported package that never authored it leaves the meta
+ * unsynced with NO error. Call this right after registering a batch (startup,
+ * import/update, reload) so a gap is visible at the moment it enters the registry.
+ *
+ * Returns the missing node types so callers can surface them in an API response too.
+ */
+export function warnMissingNodeMeta(defs: any[], context: string): { total: number; missing: string[] } {
+  const missing = defs
+    .filter((d: any) => !d?.whenToUse || !String(d.whenToUse).trim())
+    .map((d: any) => d?.type)
+    .filter(Boolean);
+  // Only the shortfall is worth saying. "All 84 nodes have whenToUse" is the expected
+  // state and a line that only ever reports success trains you to skim past it.
+  if (missing.length > 0) {
+    const named = `${missing.slice(0, 10).join(", ")}${missing.length > 10 ? `, and ${missing.length - 10} more` : ""}`;
+    const text =
+      `${missing.length} of ${defs.length} nodes have no whenToUse, so catalog ranking is degraded for them: ` +
+      `${named}. Author whenToUse on the node, then rebuild and restart.`;
+    if (boot.isBooting()) boot.notice("warn", text);
+    else console.warn(`[${context}] ${text}`);
+  }
+  return { total: defs.length, missing };
+}

package/vendor/base/src/plugins/state.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin State — in-memory cache sourced from PostgreSQL
+ */
+
+import { persistPluginState, removePluginState, fetchPluginState } from "../platform/serviceCalls.js";
+import { boot } from "../boot.js";
+
+export type PluginStateEntry = {
+  enabled: boolean;
+  version: string;
+  source: string;
+  metadata?: any;
+};
+
+let PLUGIN_STATE: Map<string, PluginStateEntry> = new Map();
+
+export function getPluginState(name: string): PluginStateEntry | undefined {
+  return PLUGIN_STATE.get(name);
+}
+
+export function setPluginState(name: string, state: PluginStateEntry): void {
+  PLUGIN_STATE.set(name, state);
+}
+
+export function isPluginEnabled(name: string): boolean {
+  const state = PLUGIN_STATE.get(name);
+  if (!state) return true;
+  return state.enabled;
+}
+
+export async function loadStateFromPostgres(): Promise<void> {
+  const pgState = await fetchPluginState();
+  PLUGIN_STATE.clear();
+  if (pgState.length > 0) {
+    boot.pluginStates(pgState.length);
+    for (const plugin of pgState) {
+      PLUGIN_STATE.set(plugin.name, {
+        enabled: plugin.enabled,
+        version: plugin.version,
+        source: plugin.source,
+        metadata: plugin.metadata,
+      });
+    }
+  }
+}
+
+/** All state entries (the in-memory mirror of installed_plugins). Used by the
+ *  registry-toggle routes to read enable/spatial state for skills/apps/nodes. */
+export function listPluginState(): Array<{ name: string } & PluginStateEntry> {
+  return [...PLUGIN_STATE.entries()].map(([name, state]) => ({ name, ...state }));
+}
+
+export { persistPluginState, removePluginState };