@nocobase/flow-engine 2.0.0-beta.20 → 2.0.0-beta.22

package/src/runjs-context/contributions.ts

@@ -0,0 +1,88 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { FlowRunJSContext } from '../flowContext';
+import { RunJSContextRegistry, type RunJSVersion } from './registry';
+
+export type RunJSContextContributionApi = {
+  version: RunJSVersion;
+  RunJSContextRegistry: typeof RunJSContextRegistry;
+  FlowRunJSContext: typeof FlowRunJSContext;
+};
+
+export type RunJSContextContribution = (api: RunJSContextContributionApi) => void | Promise<void>;
+
+const contributions = new Set<RunJSContextContribution>();
+const appliedByVersion = new Map<RunJSVersion, Set<RunJSContextContribution>>();
+const setupDoneVersions = new Set<RunJSVersion>();
+
+async function applyContributionOnce(version: RunJSVersion, contribution: RunJSContextContribution) {
+  const applied = appliedByVersion.get(version) || new Set<RunJSContextContribution>();
+  appliedByVersion.set(version, applied);
+  if (applied.has(contribution)) return;
+
+  // Mark as applied before awaiting to avoid duplicate runs on concurrency.
+  // If it fails, remove the marker so a later setup retry can re-apply.
+  applied.add(contribution);
+  try {
+    await contribution({
+      version,
+      RunJSContextRegistry,
+      FlowRunJSContext,
+    });
+  } catch (error) {
+    applied.delete(contribution);
+    throw error;
+  }
+}
+
+/**
+ * Register a RunJS context/doc contribution.
+ *
+ * - If RunJS contexts have already been set up for a version, the contribution is applied immediately once.
+ * - Each contribution is executed at most once per version.
+ */
+export function registerRunJSContextContribution(contribution: RunJSContextContribution) {
+  if (typeof contribution !== 'function') {
+    throw new Error('[flow-engine] registerRunJSContextContribution: contribution must be a function');
+  }
+  if (contributions.has(contribution)) return;
+  contributions.add(contribution);
+
+  // Apply immediately for already-setup versions (late registration).
+  for (const version of setupDoneVersions) {
+    void applyContributionOnce(version, contribution).catch((error) => {
+      // Avoid unhandled rejections in late registrations
+      try {
+        // eslint-disable-next-line no-console
+        console.error('[flow-engine] RunJS context contribution failed:', error);
+      } catch (_) {
+        void 0;
+      }
+    });
+  }
+}
+
+/**
+ * Apply all registered contributions for a given version.
+ * Intended to be called by setupRunJSContexts().
+ */
+export async function applyRunJSContextContributions(version: RunJSVersion) {
+  for (const contribution of contributions) {
+    await applyContributionOnce(version, contribution);
+  }
+}
+
+/**
+ * Mark setupRunJSContexts() as completed for a given version.
+ * Used to support late contributions that should take effect without re-running setup.
+ */
+export function markRunJSContextsSetupDone(version: RunJSVersion) {
+  setupDoneVersions.add(version);
+}

package/src/runjs-context/setup.ts

@@ -13,6 +13,7 @@
 import { RunJSContextRegistry } from './registry';
 import { FlowRunJSContext } from '../flowContext';
 import { defineBaseContextMeta } from './contexts/base';
+import { applyRunJSContextContributions, markRunJSContextsSetupDone } from './contributions';
 
 let done = false;
 export async function setupRunJSContexts() {
@@ -23,6 +24,7 @@ export async function setupRunJSContexts() {
   const [
     { JSBlockRunJSContext },
     { JSFieldRunJSContext },
+    { JSEditableFieldRunJSContext },
     { JSItemRunJSContext },
     { JSColumnRunJSContext },
     { FormJSFieldItemRunJSContext },
@@ -31,6 +33,7 @@ export async function setupRunJSContexts() {
   ] = await Promise.all([
     import('./contexts/JSBlockRunJSContext'),
     import('./contexts/JSFieldRunJSContext'),
+    import('./contexts/JSEditableFieldRunJSContext'),
     import('./contexts/JSItemRunJSContext'),
     import('./contexts/JSColumnRunJSContext'),
     import('./contexts/FormJSFieldItemRunJSContext'),
@@ -42,10 +45,13 @@ export async function setupRunJSContexts() {
   RunJSContextRegistry.register(v1, '*', FlowRunJSContext);
   RunJSContextRegistry.register(v1, 'JSBlockModel', JSBlockRunJSContext, { scenes: ['block'] });
   RunJSContextRegistry.register(v1, 'JSFieldModel', JSFieldRunJSContext, { scenes: ['detail'] });
+  RunJSContextRegistry.register(v1, 'JSEditableFieldModel', JSEditableFieldRunJSContext, { scenes: ['form'] });
   RunJSContextRegistry.register(v1, 'JSItemModel', JSItemRunJSContext, { scenes: ['form'] });
   RunJSContextRegistry.register(v1, 'JSColumnModel', JSColumnRunJSContext, { scenes: ['table'] });
   RunJSContextRegistry.register(v1, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext, { scenes: ['form'] });
   RunJSContextRegistry.register(v1, 'JSRecordActionModel', JSRecordActionRunJSContext, { scenes: ['table'] });
   RunJSContextRegistry.register(v1, 'JSCollectionActionModel', JSCollectionActionRunJSContext, { scenes: ['table'] });
+  await applyRunJSContextContributions(v1);
   done = true;
+  markRunJSContextsSetupDone(v1);
 }

package/src/runjs-context/snippets/index.ts

@@ -9,8 +9,10 @@
 
 import { RunJSContextRegistry } from '../registry';
 
+export type RunJSSnippetLoader = () => Promise<any>;
+
 // Simple manual exports - no build-time magic needed
-const snippets: Record<string, () => Promise<any>> = {
+const snippets: Record<string, RunJSSnippetLoader | undefined> = {
   // global
   'global/message-success': () => import('./global/message-success.snippet'),
   'global/message-error': () => import('./global/message-error.snippet'),
@@ -69,6 +71,32 @@ const snippets: Record<string, () => Promise<any>> = {
 
 export default snippets;
 
+/**
+ * Register a RunJS snippet loader for editors/AI coding.
+ *
+ * - By default, an existing ref will NOT be overwritten (returns false).
+ * - Use { override: true } to overwrite an existing ref (returns true).
+ */
+export function registerRunJSSnippet(
+  ref: string,
+  loader: RunJSSnippetLoader,
+  options?: {
+    override?: boolean;
+  },
+): boolean {
+  if (typeof ref !== 'string' || !ref.trim()) {
+    throw new Error('[flow-engine] registerRunJSSnippet: ref must be a non-empty string');
+  }
+  if (typeof loader !== 'function') {
+    throw new Error('[flow-engine] registerRunJSSnippet: loader must be a function returning a Promise');
+  }
+  const key = ref.trim();
+  const existed = typeof snippets[key] === 'function';
+  if (existed && !options?.override) return false;
+  snippets[key] = loader;
+  return true;
+}
+
 // Cohesive snippet helpers for clients (editor, etc.)
 type EngineSnippetEntry = {
   name: string;
@@ -127,8 +155,8 @@ function resolveLocaleMeta(def: any, locale?: string) {
 }
 
 export async function getSnippetBody(ref: string): Promise<string> {
-  const loader = (snippets as any)[ref];
-  if (!loader) throw new Error(`[flow-engine] snippet not found: ${ref}`);
+  const loader = snippets[ref];
+  if (typeof loader !== 'function') throw new Error(`[flow-engine] snippet not found: ${ref}`);
   const mod = await loader();
   const def = mod?.default;
   // engine snippet modules export a SnippetModule as default
@@ -152,46 +180,52 @@ export async function listSnippetsForContext(
   }
   await Promise.all(
     Object.entries(snippets).map(async ([key, loader]) => {
-      const mod = await (loader as any)();
-      const def = mod?.default || {};
-      const body: any = def?.content ?? mod?.content;
-      if (typeof body !== 'string') return;
-      let ok = true;
-      if (Array.isArray(def?.contexts) && def.contexts.length) {
-        const ctxNames = def.contexts.map((item: any) => {
-          if (item === '*') return '*';
-          if (typeof item === 'string') return item;
-          if (typeof item === 'function') return item.name || '*';
-          if (item && typeof item === 'object' && typeof item.name === 'string') return item.name;
-          return String(item ?? '');
-        });
-        if (ctxClassName === '*') {
-          // '*' means return all snippets without filtering by context
-          ok = true;
-        } else {
-          ok = ctxNames.includes('*') || ctxNames.some((name: string) => allowedContextNames.has(name));
+      if (typeof loader !== 'function') return;
+      try {
+        const mod = await loader();
+        const def = mod?.default || {};
+        const body: any = def?.content ?? mod?.content;
+        if (typeof body !== 'string') return;
+        let ok = true;
+        if (Array.isArray(def?.contexts) && def.contexts.length) {
+          const ctxNames = def.contexts.map((item: any) => {
+            if (item === '*') return '*';
+            if (typeof item === 'string') return item;
+            if (typeof item === 'function') return item.name || '*';
+            if (item && typeof item === 'object' && typeof item.name === 'string') return item.name;
+            return String(item ?? '');
+          });
+          if (ctxClassName === '*') {
+            // '*' means return all snippets without filtering by context
+            ok = true;
+          } else {
+            ok = ctxNames.includes('*') || ctxNames.some((name: string) => allowedContextNames.has(name));
+          }
         }
+        if (ok && Array.isArray(def?.versions) && def.versions.length) {
+          ok = def.versions.includes('*') || def.versions.includes(version);
+        }
+        if (!ok) return;
+        const localeMeta = resolveLocaleMeta(def, locale);
+        const name = localeMeta.label || def?.label || deriveNameFromKey(key);
+        const description = localeMeta.description ?? def?.description;
+        const prefix = def?.prefix || name;
+        const groups = computeGroups(def, key);
+        const scenes = normalizeScenes(def, key);
+        entries.push({
+          name,
+          prefix,
+          description,
+          body,
+          ref: key,
+          group: groups[0],
+          groups,
+          scenes,
+        });
+      } catch (_) {
+        // fail-open: ignore broken snippet loader
+        return;
       }
-      if (ok && Array.isArray(def?.versions) && def.versions.length) {
-        ok = def.versions.includes('*') || def.versions.includes(version);
-      }
-      if (!ok) return;
-      const localeMeta = resolveLocaleMeta(def, locale);
-      const name = localeMeta.label || def?.label || deriveNameFromKey(key);
-      const description = localeMeta.description ?? def?.description;
-      const prefix = def?.prefix || name;
-      const groups = computeGroups(def, key);
-      const scenes = normalizeScenes(def, key);
-      entries.push({
-        name,
-        prefix,
-        description,
-        body,
-        ref: key,
-        group: groups[0],
-        groups,
-        scenes,
-      });
     }),
   );
   return entries;

package/src/utils/__tests__/safeGlobals.test.ts

@@ -28,6 +28,14 @@ describe('safeGlobals', () => {
     expect(win.console).toBeDefined();
     expect(win.foo).toBe(123);
     expect(new win.FormData()).toBeInstanceOf(window.FormData);
+    if (typeof window.Blob !== 'undefined') {
+      expect(typeof win.Blob).toBe('function');
+      expect(new win.Blob(['x'])).toBeInstanceOf(window.Blob);
+    }
+    if (typeof window.URL !== 'undefined') {
+      expect(win.URL).toBe(window.URL);
+      expect(typeof win.URL.createObjectURL).toBe('function');
+    }
     // access to location proxy is allowed, but sensitive props throw
     expect(() => win.location.href).toThrow(/not allowed/);
   });

package/src/utils/safeGlobals.ts

@@ -9,7 +9,7 @@
 
 /**
  * 统一的安全全局对象代理：window/document/navigator
- * - window：仅允许常用的定时器、console、Math、Date、FormData、addEventListener、open（安全包装）、location（安全代理）
+ * - window：仅允许常用的定时器、console、Math、Date、FormData、Blob、URL、addEventListener、open（安全包装）、location（安全代理）
  * - document：仅允许 createElement/querySelector/querySelectorAll
  * - navigator：仅提供极少量低风险能力（clipboard.writeText、onLine、language、languages）
  * - 不允许随意访问未声明的属性，最小权限原则
@@ -211,6 +211,8 @@ export function createSafeWindow(extra?: Record<string, any>) {
     Math,
     Date,
     FormData,
+    ...(typeof Blob !== 'undefined' ? { Blob } : {}),
+    ...(typeof URL !== 'undefined' ? { URL } : {}),
     // 事件侦听仅绑定到真实 window，便于少量需要的全局监听
     addEventListener: addEventListener.bind(window),
     // 安全的 window.open 代理