RunJS Plugin Extension Points (ctx Documentation / Snippets / Scene Mapping)

When a plugin adds or extends RunJS capabilities, it is recommended to register the "context mapping / ctx documentation / example code" through official extension points. This ensures:

• CodeEditor can provide auto-completion for ctx.xxx.yyy.
• AI coding can obtain structured ctx API references and examples.

This chapter introduces two extension points:

• registerRunJSContextContribution(...)
• registerRunJSSnippet(...)

1. registerRunJSContextContribution

Used to register RunJS "contributions." Typical use cases include:

• Adding/overriding RunJSContextRegistry mappings (modelClass -> RunJSContext, including scenes).
• Extending RunJSDocMeta (descriptions/examples/completion templates for the ctx API) for FlowRunJSContext or custom RunJSContext.

Behavior Description

• Contributions are executed collectively during the setupRunJSContexts() phase.
• If setupRunJSContexts() has already completed, late registrations will be executed immediately (no need to re-run setup).
• Each contribution will be executed at most once for each RunJSVersion.

Example: Adding a JS-writable Model Context

import { registerRunJSContextContribution, FlowRunJSContext, RunJSContextRegistry } from '@nocobase/flow-engine';

registerRunJSContextContribution(({ version, FlowRunJSContext: BaseCtx, RunJSContextRegistry: Registry }) => {
  if (version !== 'v1') return;

  class MyPluginRunJSContext extends BaseCtx {}

  // 1) ctx documentation/completion (RunJSDocMeta)
  MyPluginRunJSContext.define({
    label: 'MyPlugin RunJS context',
    properties: {
      myPlugin: {
        description: 'My plugin namespace',
        detail: 'object',
        properties: {
          hello: {
            description: 'Say hello',
            detail: '(name: string) => string',
            completion: { insertText: `ctx.myPlugin.hello('World')` },
          },
        },
      },
    },
  });

  // 2) model -> context mapping (scene affects editor completion/snippet filtering)
  Registry.register('v1', 'MyPluginJSModel', MyPluginRunJSContext, { scenes: ['block'] });
});

2. registerRunJSSnippet

Used to register example code snippets for RunJS, which are used for:

• CodeEditor snippet completion.
• Serving as examples/reference materials for AI coding (can be filtered by scene/version/locale).

Recommended ref Naming

It is suggested to use: plugin/<pluginName>/<topic>, for example:

• plugin/plugin-my/foo
• plugin/plugin-my/api-request-example

Avoid conflicts with core global/* or scene/* namespaces.

Conflict Strategy

• By default, existing ref entries are not overwritten (returns false without throwing an error).
• To explicitly overwrite, pass { override: true }.

Example: Registering a Snippet

import { registerRunJSSnippet } from '@nocobase/flow-engine';

registerRunJSSnippet('plugin/plugin-my/hello', async () => ({
  default: {
    label: 'Hello (My Plugin)',
    description: 'Minimal example for my plugin',
    prefix: 'my-hello',
    versions: ['v1'],
    scenes: ['block'],
    contexts: ['*'],
    content: `
// My plugin snippet
ctx.message.success('Hello from plugin');
`,
  },
}));

3. Best Practices

• Layered Maintenance of Documentation + Snippets:
  • RunJSDocMeta: Descriptions/completion templates (short, structured).
  • Snippets: Long examples (reusable, filterable by scene/version).
• Avoid Excessive Prompt Length: Examples should be concise; prioritize "minimal runnable templates."
• Scene Priority: If your JS code primarily runs in scenarios like forms or tables, ensure the scenes field is filled correctly to improve the relevance of completions and examples.

4. Hiding Completions Based on Actual ctx: hidden(ctx)

Certain ctx APIs are highly context-specific (e.g., ctx.popup is only available when a popup or drawer is open). If you want to hide these unavailable APIs during completion, you can define hidden(ctx) for the corresponding entry in RunJSDocMeta:

• Returns true: Hides the current node and its subtree.
• Returns string[]: Hides specific sub-paths under the current node (supports returning multiple paths; paths are relative; subtrees are hidden based on prefix matching).

hidden(ctx) supports async: You can use await ctx.getVar('ctx.xxx') to determine visibility (at the user's discretion). It is recommended to keep this logic fast and side-effect-free (e.g., avoid network requests).

Example: Show ctx.popup.* completions only when popup.uid exists.

FlowRunJSContext.define({
  properties: {
    popup: {
      description: 'Popup context (async)',
      hidden: async (ctx) => !(await ctx.getVar('ctx.popup'))?.uid,
      properties: {
        uid: 'Popup uid',
      },
    },
  },
});

Example: Popup is available but some sub-paths are hidden (relative paths only; e.g., hiding record and parent.record).

FlowRunJSContext.define({
  properties: {
    popup: {
      description: 'Popup context (async)',
      hidden: async (ctx) => {
        const popup = await ctx.getVar('ctx.popup');
        if (!popup?.uid) return true;
        const hidden: string[] = [];
        if (!popup?.record) hidden.push('record');
        if (!popup?.parent?.record) hidden.push('parent.record');
        return hidden;
      },
      properties: {
        uid: 'Popup uid',
        record: 'Popup record',
        parent: {
          properties: {
            record: 'Parent record',
          },
        },
      },
    },
  },
});

Note: CodeEditor always enables completion filtering based on the actual ctx (fail-open, does not throw errors).

5. Runtime info/meta and Context Information API (for Completions and LLMs)

In addition to maintaining ctx documentation statically via FlowRunJSContext.define(), you can also inject info/meta at runtime via FlowContext.defineProperty/defineMethod. You can then output serializable context information for CodeEditor or LLMs using the following APIs:

• await ctx.getApiInfos(options?): Static API information.
• await ctx.getVarInfos(options?): Variable structure information (sourced from meta, supports path/maxDepth expansion).
• await ctx.getEnvInfos(): Runtime environment snapshot.

5.1 defineMethod(name, fn, info?)

info supports (all optional):

• description / detail / examples
• ref: string | { url: string; title?: string }
• params / returns (JSDoc-like)

Note: getApiInfos() outputs static API documentation and will not include fields like deprecated, disabled, or disabledReason.

Example: Providing documentation links for ctx.refreshTargets().

ctx.defineMethod('refreshTargets', async () => {
  // ...
}, {
  description: 'Refresh data of the target blocks',
  detail: '() => Promise<void>',
  ref: { url: 'https://docs.nocobase.com/', title: 'Docs' },
});

5.2 defineProperty(key, { meta?, info? })

• meta: Used for the variable selector UI (getPropertyMetaTree / FlowContextSelector). It determines visibility, tree structure, disabling, etc. (supports functions/async).
  • Common fields: title / type / properties / sort / hidden / disabled / disabledReason / buildVariablesParams
• info: Used for static API documentation (getApiInfos) and descriptions for LLMs. It does not affect the variable selector UI (supports functions/async).
  • Common fields: title / type / interface / description / examples / ref / params / returns

When only meta is provided (without info):

• getApiInfos() will not return this key (as static API docs are not inferred from meta).
• getVarInfos() will build the variable structure based on meta (used for variable selectors/dynamic variable trees).

5.3 Context Information API

Used to output "available context capability information."

type FlowContextInfosEnvNode = {
  description?: string;
  getVar?: string; // Can be used directly in await ctx.getVar(getVar), recommended to start with "ctx."
  value?: any; // Resolved static value (serializable, returned only when inferable)
  properties?: Record<string, FlowContextInfosEnvNode>;
};

type FlowContextApiInfos = Record<string, any>; // Static documentation (top-level)
type FlowContextVarInfos = Record<string, any>; // Variable structure (expandable by path/maxDepth)
type FlowContextEnvInfos = {
  popup?: FlowContextInfosEnvNode;
  block?: FlowContextInfosEnvNode;
  flowModel?: FlowContextInfosEnvNode;
  resource?: FlowContextInfosEnvNode;
  record?: FlowContextInfosEnvNode;
  currentViewBlocks?: FlowContextInfosEnvNode;
};

Common parameters:

• getApiInfos({ version }): RunJS documentation version (defaults to v1).
• getVarInfos({ path, maxDepth }): Trimming and maximum expansion depth (defaults to 3).

Note: The results returned by the above APIs do not contain functions and are suitable for direct serialization to LLMs.

5.4 await ctx.getVar(path)

When you have a "variable path string" (e.g., from configuration or user input) and want to retrieve the runtime value of that variable directly, use getVar:

• Example: const v = await ctx.getVar('ctx.record.roles.id')
• path is an expression path starting with ctx. (e.g., ctx.record.id / ctx.record.roles[0].id).

Additionally: Methods or properties starting with an underscore _ are treated as private members and will not appear in the output of getApiInfos() or getVarInfos().