plugin-build-visualization-block 0.1.1

package/src/server/plugin.ts

@@ -0,0 +1,255 @@
+import { InstallOptions, Plugin } from '@nocobase/server';
+import { resolve } from 'path';
+import type { ZodTypeAny } from 'zod';
+import { COLLECTION_NAME, SETTINGS_COLLECTION_NAME } from '../shared/constants';
+import {
+  build,
+  getResult,
+  recoverInterruptedBuilds,
+  registerBuildQueue,
+  retry,
+  startBuildQueueProcessor,
+  unregisterBuildQueue,
+} from './actions/build';
+import aiVisualizationBuildSettings from './resource/settings';
+import { buildVisualizationBlockTool } from './tools';
+
+/**
+ * Minimal shape of the `collections` repository we rely on here. The full
+ * repository carries many members we do not use; declaring only `db2cm`
+ * isolates the loose typing to this narrow surface instead of spreading `any`.
+ */
+interface CollectionsRepository {
+  db2cm(collectionName: string): Promise<unknown>;
+}
+
+/**
+ * The minimal shape of a registerable AI tool descriptor, mirroring the default
+ * export of `./tools/*`. Typing this (rather than `any`) keeps the tool mapping
+ * in {@link PluginBuildVisualizationBlockServer.registerAITools} type-safe.
+ */
+interface AIToolDescriptor {
+  groupName: string;
+  tool: {
+    name: string;
+    title: string;
+    description: string;
+    execution: string;
+    schema: ZodTypeAny;
+    invoke: (...args: unknown[]) => unknown;
+  };
+}
+
+/**
+ * The minimal surface of the (untyped) `aiManager.toolsManager` we depend on.
+ * The AI subsystem is not typed against the server core, so we narrow it to the
+ * single `registerTools` method we call.
+ */
+interface AIToolsManagerLike {
+  registerTools(tools: Record<string, unknown>[]): void;
+}
+
+/**
+ * Server-side plugin for `plugin-build-visualization-block`.
+ *
+ * Lifecycle responsibilities:
+ * - `beforeLoad`: import the collection definitions so the database/model layer
+ *   is available before resources are registered.
+ * - `load`: register resource actions, ACL snippets, AI tools, and lifecycle
+ *   handlers for the asynchronous build queue.
+ * - `afterStart` / `beforeStop`: start and stop the runtime queue processor.
+ * - `install` / `upgrade`: reconcile schema idempotently for fresh installs and
+ *   upgrades.
+ */
+export class PluginBuildVisualizationBlockServer extends Plugin {
+  private readonly schemaCollections = [COLLECTION_NAME, SETTINGS_COLLECTION_NAME];
+
+  afterAdd() {}
+
+  async beforeLoad() {
+    await this.db.import({
+      directory: resolve(__dirname, 'collections'),
+    });
+  }
+
+  async load() {
+    // Build / retry / poll action handlers (Req 10.1, 12.3, 9.4).
+    this.app.resourceManager.registerActionHandlers({
+      'aiVisualizationBuilds:build': build,
+      'aiVisualizationBuilds:retry': retry,
+      'aiVisualizationBuilds:getResult': getResult,
+    });
+    this.app.resourceManager.define(aiVisualizationBuildSettings);
+
+    // The polling read is allowed to any logged-in user; ownership/permission
+    // is enforced inside the action and via the per-collection `list` check.
+    this.app.acl.allow('aiVisualizationBuilds', 'getResult', 'loggedIn');
+    this.app.acl.allow(SETTINGS_COLLECTION_NAME, 'publicGet', 'loggedIn');
+
+    // ACL snippet so the resource's CRUD + build actions can be granted to a
+    // role from the plugin-manager permissions UI (Req 13.1).
+    this.app.acl.registerSnippet({
+      name: 'pm.ai-build-visualization',
+      actions: [
+        'aiVisualizationBuilds:create',
+        'aiVisualizationBuilds:update',
+        'aiVisualizationBuilds:destroy',
+        'aiVisualizationBuilds:list',
+        'aiVisualizationBuilds:get',
+        'aiVisualizationBuilds:build',
+        'aiVisualizationBuilds:retry',
+        'aiVisualizationBuilds:getResult',
+      ],
+    });
+    this.app.acl.registerSnippet({
+      name: 'pm.plugin-build-visualization-block.settings',
+      actions: [`${SETTINGS_COLLECTION_NAME}:get`, `${SETTINGS_COLLECTION_NAME}:update`],
+    });
+
+    registerBuildQueue(this.app);
+
+    // Start runtime queue services only after the app has started, then resume
+    // builds that were interrupted before their worker finished.
+    this.app.on('afterStart', async () => {
+      startBuildQueueProcessor(this.app);
+      try {
+        await recoverInterruptedBuilds(this.app);
+      } catch (err) {
+        this.app.logger.warn('[plugin-build-visualization-block] Failed to recover interrupted builds', err);
+      }
+    });
+    this.app.on('beforeStop', () => {
+      unregisterBuildQueue(this.app);
+    });
+    this.app.on('beforeDestroy', () => {
+      unregisterBuildQueue(this.app);
+    });
+
+    this.registerAITools();
+  }
+
+  /**
+   * Register the `build_visualization_block` AI tool through the AI plugin's
+   * tools manager so an AI chat agent can initiate a build. The AI subsystem is
+   * untyped against the server core, so the manager is resolved through a
+   * narrow cast and guarded for absence (the plugin must not hard-depend on the
+   * AI plugin being installed).
+   */
+  private registerAITools() {
+    const toolsManager = (this.app as unknown as { aiManager?: { toolsManager?: AIToolsManagerLike } }).aiManager
+      ?.toolsManager;
+    if (!toolsManager) {
+      this.app.logger.warn(
+        '[plugin-build-visualization-block] aiManager.toolsManager is not available; skipping tool registration',
+      );
+      return;
+    }
+
+    const tools: AIToolDescriptor[] = [buildVisualizationBlockTool];
+    toolsManager.registerTools(
+      tools.map((item) => {
+        const name = `${item.groupName}-${item.tool.name}`;
+        return {
+          scope: 'CUSTOM',
+          defaultPermission: item.tool.execution === 'backend' ? 'ALLOW' : 'ASK',
+          execution: item.tool.execution,
+          introduction: {
+            title: item.tool.title,
+            about: item.tool.description,
+          },
+          definition: {
+            name,
+            description: item.tool.description,
+            schema: item.tool.schema,
+          },
+          invoke: item.tool.invoke,
+        };
+      }),
+    );
+  }
+
+  private async ensureCollectionSchema(collectionName: string) {
+    const collection = this.db.getCollection(collectionName);
+    if (!collection) {
+      this.app.logger.warn(`[plugin-build-visualization-block] Collection "${collectionName}" is not registered`);
+      return;
+    }
+
+    const queryInterface = this.db.sequelize.getQueryInterface();
+    const tableName = collection.getTableNameWithSchema();
+    let columns: Record<string, unknown> | null = null;
+
+    try {
+      columns = await queryInterface.describeTable(tableName);
+    } catch (error) {
+      await collection.model.sync();
+      columns = await queryInterface.describeTable(tableName);
+    }
+
+    const attributes = collection.model.rawAttributes;
+    for (const [attributeName, attribute] of Object.entries(attributes)) {
+      const columnName = attribute.field || attributeName;
+      if (columns[columnName]) {
+        continue;
+      }
+
+      // `rawAttributes` entries carry runtime-only members (`Model`,
+      // `fieldName`) that are not valid column definitions; strip them via a
+      // loose record before handing the definition to the query interface.
+      const columnDefinition: Record<string, unknown> = { ...attribute };
+      delete columnDefinition.Model;
+      delete columnDefinition.fieldName;
+
+      await queryInterface.addColumn(
+        tableName,
+        columnName,
+        columnDefinition as Parameters<typeof queryInterface.addColumn>[2],
+      );
+      columns[columnName] = columnDefinition;
+      this.app.logger.info(
+        `[plugin-build-visualization-block] Added missing column "${columnName}" to "${collectionName}"`,
+      );
+    }
+  }
+
+  private async ensureSchema() {
+    for (const collectionName of this.schemaCollections) {
+      await this.ensureCollectionSchema(collectionName);
+    }
+
+    const repo = this.db.getRepository('collections') as unknown as CollectionsRepository | undefined;
+    if (repo) {
+      for (const collectionName of this.schemaCollections) {
+        await repo.db2cm(collectionName);
+      }
+    }
+  }
+
+  async install(options?: InstallOptions) {
+    await this.ensureSchema();
+  }
+
+  async upgrade() {
+    await this.ensureSchema();
+  }
+
+  async afterEnable() {}
+
+  async beforeDisable() {
+    unregisterBuildQueue(this.app);
+  }
+
+  async afterDisable() {
+    unregisterBuildQueue(this.app);
+  }
+
+  async beforeUnload() {
+    unregisterBuildQueue(this.app);
+  }
+
+  async remove() {
+    unregisterBuildQueue(this.app);
+  }
+}
+
+export default PluginBuildVisualizationBlockServer;

package/src/server/resource/settings.ts

@@ -0,0 +1,97 @@
+import type { ResourceOptions } from '@nocobase/resourcer';
+
+import { MAX_COLLECTIONS, SETTINGS_COLLECTION_NAME } from '../../shared/constants';
+
+interface SettingsRecord {
+  id?: number | string;
+  defaultDataSource?: string | null;
+  defaultCollections?: unknown;
+  defaultLLMService?: string | null;
+  defaultModel?: string | null;
+  enableAITool?: boolean | null;
+  get?(key: string): unknown;
+  update(values: Record<string, unknown>): Promise<void>;
+}
+
+interface SettingsRepository {
+  findOne(): Promise<SettingsRecord | null>;
+  create(options: { values: Record<string, unknown> }): Promise<SettingsRecord>;
+}
+
+const DEFAULT_SETTINGS = {
+  defaultCollections: [],
+  enableAITool: true,
+};
+
+function readRecordValue(record: SettingsRecord, key: string): unknown {
+  if (typeof record.get === 'function') {
+    return record.get(key);
+  }
+  return (record as Record<string, unknown>)[key];
+}
+
+function normalizeCollections(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string' && item.length > 0).slice(0, MAX_COLLECTIONS);
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function serializeSettings(record: SettingsRecord) {
+  return {
+    defaultDataSource: normalizeOptionalString(readRecordValue(record, 'defaultDataSource')),
+    defaultCollections: normalizeCollections(readRecordValue(record, 'defaultCollections')),
+    defaultLLMService: normalizeOptionalString(readRecordValue(record, 'defaultLLMService')),
+    defaultModel: normalizeOptionalString(readRecordValue(record, 'defaultModel')),
+    enableAITool: readRecordValue(record, 'enableAITool') !== false,
+  };
+}
+
+function sanitizeValues(values: unknown) {
+  const source = values && typeof values === 'object' ? (values as Record<string, unknown>) : {};
+  return {
+    defaultDataSource: normalizeOptionalString(source.defaultDataSource),
+    defaultCollections: normalizeCollections(source.defaultCollections),
+    defaultLLMService: normalizeOptionalString(source.defaultLLMService),
+    defaultModel: normalizeOptionalString(source.defaultModel),
+    enableAITool: source.enableAITool !== false,
+  };
+}
+
+async function getSettings(ctx: { db: { getRepository(name: string): SettingsRepository } }) {
+  const repo = ctx.db.getRepository(SETTINGS_COLLECTION_NAME);
+  const existing = await repo.findOne();
+  if (existing) {
+    return existing;
+  }
+  return repo.create({ values: DEFAULT_SETTINGS });
+}
+
+export const aiVisualizationBuildSettings: ResourceOptions = {
+  name: SETTINGS_COLLECTION_NAME,
+  actions: {
+    get: async (ctx, next) => {
+      const settings = await getSettings(ctx);
+      ctx.body = serializeSettings(settings);
+      await next();
+    },
+    publicGet: async (ctx, next) => {
+      const settings = await getSettings(ctx);
+      ctx.body = serializeSettings(settings);
+      await next();
+    },
+    update: async (ctx, next) => {
+      const settings = await getSettings(ctx);
+      const nextValues = sanitizeValues(ctx.action.params.values);
+      await settings.update(nextValues);
+      ctx.body = nextValues;
+      await next();
+    },
+  },
+};
+
+export default aiVisualizationBuildSettings;

package/src/server/tools/build-visualization-block.ts

@@ -0,0 +1,173 @@
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+
+import type { Application } from '@nocobase/server';
+import { COLLECTION_NAME, MAX_COLLECTIONS, MIN_COLLECTIONS, SETTINGS_COLLECTION_NAME } from '../../shared/constants';
+import { enqueueBuild } from '../actions/build';
+
+/**
+ * The zod input schema for the `build_visualization_block` AI tool. The shape
+ * mirrors the inputs accepted by the `aiVisualizationBuilds:build` action so an
+ * AI chat agent can initiate a build the same way the client form does.
+ */
+const buildVisualizationBlockSchema = z.object({
+  requirement: z.string().describe('Natural-language description of the visualization block to build.'),
+  collections: z
+    .array(z.string())
+    .min(MIN_COLLECTIONS)
+    .max(MAX_COLLECTIONS)
+    .optional()
+    .describe('The selected target collection names the block should be built from.'),
+  dataSource: z.string().optional().describe('The data source key. Defaults to the main data source when omitted.'),
+  llmService: z.string().optional().describe('The AI/LLM service to use for generation.'),
+  model: z.string().optional().describe('The model to use for generation.'),
+});
+
+/** The validated argument shape derived from {@link buildVisualizationBlockSchema}. */
+type BuildVisualizationBlockArgs = z.infer<typeof buildVisualizationBlockSchema>;
+
+/**
+ * A minimal structural view of the repository methods this tool relies on. The
+ * full NocoBase repository type is not imported here to keep the tool decoupled
+ * from server internals; only `create` is used.
+ */
+interface BuildRecordRepository {
+  create(options: { values: Record<string, unknown> }): Promise<{ get(key: string): unknown }>;
+}
+
+interface SettingsRepository {
+  findOne(): Promise<{
+    defaultDataSource?: string | null;
+    defaultCollections?: unknown;
+    defaultLLMService?: string | null;
+    defaultModel?: string | null;
+    enableAITool?: boolean | null;
+    get?(key: string): unknown;
+  } | null>;
+}
+
+/**
+ * A minimal structural view of the invocation context passed to the tool. It is
+ * intentionally narrow (rather than `any`) so the tool only depends on the
+ * surface it actually uses.
+ */
+interface BuildVisualizationToolContext {
+  app: Application & {
+    db: Application['db'] & {
+      getRepository(name: typeof COLLECTION_NAME): BuildRecordRepository;
+      getRepository(name: typeof SETTINGS_COLLECTION_NAME): SettingsRepository;
+    };
+    logger: {
+      error(message: string, meta?: unknown): void;
+    };
+  };
+  auth?: {
+    user?: {
+      id?: number | string;
+    };
+  };
+}
+
+function normalizeCollections(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string' && item.length > 0).slice(0, MAX_COLLECTIONS);
+}
+
+function normalizeOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readRecordValue(record: { get?(key: string): unknown } | null | undefined, key: string): unknown {
+  if (!record) {
+    return undefined;
+  }
+  if (typeof record.get === 'function') {
+    return record.get(key);
+  }
+  return (record as Record<string, unknown>)[key];
+}
+
+/**
+ * The `build_visualization_block` AI tool. Registered via
+ * `aiManager.toolsManager.registerTools` (wired in `plugin.ts` by task 7.4),
+ * matching the export shape used by `plugin-build-guide-block`.
+ */
+export default {
+  groupName: 'plugin-build-visualization',
+  tool: {
+    name: 'build_visualization_block',
+    title: 'Build Visualization Block',
+    description: 'Generate a NocoBase chart/table/form block from a requirement and selected collections.',
+    execution: 'backend',
+    schema: buildVisualizationBlockSchema,
+    invoke: async (ctx: BuildVisualizationToolContext, args: BuildVisualizationBlockArgs) => {
+      try {
+        const { requirement } = args;
+        const { db } = ctx.app;
+        const settings = await db.getRepository(SETTINGS_COLLECTION_NAME).findOne();
+        if (readRecordValue(settings, 'enableAITool') === false) {
+          return { status: 'error', content: 'Build Visualization Block AI tool is disabled.' };
+        }
+
+        const collections = args.collections?.length
+          ? args.collections
+          : normalizeCollections(readRecordValue(settings, 'defaultCollections'));
+        const dataSource = args.dataSource ?? normalizeOptionalString(readRecordValue(settings, 'defaultDataSource'));
+        const llmService = args.llmService ?? normalizeOptionalString(readRecordValue(settings, 'defaultLLMService'));
+        const model = args.model ?? normalizeOptionalString(readRecordValue(settings, 'defaultModel'));
+
+        if (collections.length < MIN_COLLECTIONS) {
+          return { status: 'error', content: 'At least one collection is required.' };
+        }
+        if (!llmService || !model) {
+          return { status: 'error', content: 'AI service and model are required.' };
+        }
+
+        const repo = db.getRepository(COLLECTION_NAME);
+        const createdById = ctx.auth?.user?.id;
+        const runId = randomUUID();
+
+        const record = await repo.create({
+          values: {
+            requirement,
+            collections,
+            dataSource,
+            primaryCollection: collections[0],
+            llmService,
+            model,
+            status: 'building',
+            buildPhase: 'queued',
+            buildRunId: runId,
+            buildQueuedAt: new Date(),
+            ...(createdById !== undefined ? { createdById } : {}),
+          },
+        });
+
+        const id = record.get('id');
+        const buildId = String(id);
+        await enqueueBuild(ctx.app, {
+          buildId,
+          runId,
+          userId: createdById ?? null,
+          queuedAt: new Date().toISOString(),
+        });
+
+        return {
+          status: 'success',
+          content: {
+            id,
+            collection: COLLECTION_NAME,
+            status: 'building',
+            buildPhase: 'queued',
+          },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.app.logger.error(`[build_visualization_block] Error: ${message}`, err);
+        return { status: 'error', content: message };
+      }
+    },
+  },
+};

package/src/server/tools/index.ts

@@ -0,0 +1 @@
+export { default as buildVisualizationBlockTool } from './build-visualization-block';