gkt-node 3.3.0

package/assets/.agent/workflows/n8n-automator.md

@@ -0,0 +1,114 @@
+---
+description: n8n Workflow Automator — Build, configure, and debug n8n workflows with Code nodes, API integrations, and 70+ SaaS connectors.
+---
+
+# n8n Workflow Automator
+
+You are an **n8n automation expert** who builds production-grade workflows connecting APIs, databases, and SaaS services. You combine deep n8n platform knowledge with JavaScript/Python coding skills and API integration expertise.
+
+## When to Use
+
+- Building or debugging n8n workflows
+- Writing Code nodes (JavaScript preferred, Python when needed)
+- Configuring HTTP Request nodes and API integrations
+- Connecting SaaS services (Slack, Google Sheets, HubSpot, etc.)
+- Designing webhook-triggered automations
+- Optimizing workflow performance and error handling
+
+## Core Skills to Load
+
+Before starting any n8n task, read the relevant skills:
+
+### n8n Platform Skills
+
+1. **n8n-mcp-tools-expert** — Node discovery, workflow management, template deployment, validation tools
+2. **n8n-node-configuration** — Operation-aware configuration, property dependencies, progressive disclosure
+3. **n8n-code-python** — Python Code nodes (use only when JavaScript isn't suitable)
+
+### Supporting Skills (load as needed)
+
+4. **workflow-automation** — Durable execution patterns, sequential/parallel/orchestrator workflows
+5. **javascript-mastery** — ES6+, async/await, promises, array methods for Code nodes
+6. **api-design-principles** — REST API patterns, request/response design, error handling
+7. **api-patterns** — REST vs GraphQL decisions, pagination, versioning
+8. **error-handling-patterns** — Try/catch, graceful degradation, retry strategies
+9. **auth-implementation-patterns** — OAuth2, API keys, JWT for API integrations
+
+### SaaS Integration Skills (load per connector)
+
+10. **zapier-make-patterns** — No-code/low-code automation comparison and patterns
+11. Any specific SaaS automation skill (e.g., `slack-automation`, `hubspot-automation`, `gmail-automation`, etc.)
+
+## Workflow
+
+### Phase 1: Understand Requirements
+
+1. Clarify the automation goal: trigger → process → output
+2. Identify data sources and destinations (APIs, databases, SaaS)
+3. Determine trigger type: webhook, schedule, manual, or event-based
+4. Map the data flow and transformations needed
+
+### Phase 2: Design Workflow Architecture
+
+1. Choose workflow pattern: sequential, parallel, or orchestrator-worker
+2. Select nodes: search available nodes with `search_nodes`
+3. Plan error handling: retry logic, fallback paths, error notifications
+4. Design for idempotency (especially for payment/critical flows)
+
+### Phase 3: Build & Configure
+
+1. Create workflow structure with proper node connections
+2. Configure each node using progressive disclosure (start minimal)
+3. Write Code nodes in **JavaScript first** (95% of cases):
+   - Use `$input.all()`, `$input.first()`, `$input.item` for data access
+   - Use `$helpers.httpRequest()` for API calls within Code nodes
+   - Return `[{json: {...}}]` format always
+4. Validate each node configuration with `validate_node`
+5. Test with sample data
+
+### Phase 4: Production Hardening
+
+1. Add error handling nodes (try/catch, IF checks)
+2. Set up retry logic for external API calls
+3. Add logging/notification for failures (Slack, email)
+4. Validate complete workflow with `validate_workflow`
+5. Activate and monitor
+
+## Key Rules
+
+### JavaScript Code Nodes (Preferred)
+
+```javascript
+// Always return this format
+return items.map((item) => ({
+  json: {
+    ...item.json,
+    processed: true,
+    timestamp: new Date().toISOString(),
+  },
+}));
+```
+
+### Python Code Nodes (Only When Needed)
+
+```python
+# Only use when you need Python stdlib (statistics, regex, etc.)
+items = _input.all()
+return [{"json": {**item["json"], "processed": True}} for item in items]
+```
+
+### API Integration Pattern
+
+```
+Webhook Trigger → HTTP Request → Code (transform) → Output (Slack/Sheet/DB)
+                                    ↓
+                              Error Handler → Notification
+```
+
+### Critical Reminders
+
+- **nodeType formats differ**: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
+- **Webhook data** is under `body`: `$json.body.fieldName`, not `$json.fieldName`
+- **Always validate** before deploying: iterate config → validate → fix → repeat
+- **JavaScript > Python** for n8n: better helpers, Luxon dates, HTTP requests
+- **No external libraries** in Python Code nodes (stdlib only)

package/assets/.agent/workflows/nocobase-plugin-build.md

@@ -0,0 +1,291 @@
+---
+description: How to build a NocoBase plugin (standalone or as part of the monorepo)
+---
+
+# NocoBase Plugin Build Guide
+
+## Prerequisites
+
+1. **Yarn workspaces** — Plugin must be in a path matching `packages/*/*` or `packages/*/*/*` in root `package.json` workspaces
+2. **`@nocobase/build`** — Must be installed (part of NocoBase core at `packages/core/build`)
+3. **`yarn install`** — Must have been run after creating a new plugin so workspaces recognize it
+
+---
+
+## Scaffold a New Plugin
+
+```bash
+# From NocoBase root — generates boilerplate in packages/plugins/@nocobase/
+yarn nocobase create-plugin @nocobase/plugin-<name>
+
+# Then register in workspace and install deps
+yarn install
+```
+
+The scaffold creates all required files (`package.json`, `client.js`, `server.js`, `src/`).
+
+---
+
+## Build Command
+
+### From NocoBase root directory:
+
+// turbo-all
+
+```bash
+# Standard build (may fail on declarations if core packages aren't built)
+npx nocobase-build @nocobase/plugin-<name>
+
+# Skip declaration generation (use when core lib/ folders don't exist)
+npx nocobase-build @nocobase/plugin-<name> --no-dts
+
+# Via yarn script (equivalent)
+yarn nocobase build @nocobase/plugin-<name>
+yarn nocobase build @nocobase/plugin-<name> --no-dts
+```
+
+### What the build does (3 phases):
+
+1. **Client** — Rspack bundles `src/client/index.tsx` → `dist/client/index.js` (externals: react, antd, @nocobase/\*)
+2. **Server** — NCC compiles `src/server/index.ts` → `dist/server/index.js` + bundled deps (externals: @nocobase/\*)
+3. **Declarations** (optional) — TypeScript `tsc` generates `.d.ts` files. **Requires** all `@nocobase/*` peer deps to have pre-built `lib/` folders
+
+---
+
+## When to use `--no-dts`
+
+Use `--no-dts` when:
+
+- You're in a **dev environment** where core packages haven't been fully built yet
+- Core packages like `@nocobase/server`, `@nocobase/client` don't have `lib/` directories
+- You just need a working runtime build for testing
+
+The `--no-dts` flag is **safe** — declarations are only needed for TypeScript consumers, not for NocoBase runtime.
+
+---
+
+## Development Mode (Hot Reload)
+
+```bash
+# Watch mode — rebuilds on file change (server only)
+yarn nocobase build @nocobase/plugin-<name> --watch
+
+# Full dev server with hot reload (requires NocoBase dev setup)
+yarn dev
+```
+
+> ⚠️ Client changes require a full browser refresh even in watch mode. Server changes require restarting the NocoBase process.
+
+---
+
+## Plugin `package.json` Requirements
+
+```json
+{
+  "name": "@nocobase/plugin-<name>",
+  "version": "1.0.0",
+  "main": "./dist/server/index.js",
+  "dependencies": {
+    "pg": "^8.x"
+  },
+  "peerDependencies": {
+    "@nocobase/client": "2.x",
+    "@nocobase/server": "2.x",
+    "@nocobase/database": "2.x"
+  },
+  "devDependencies": {
+    "@nocobase/test": "2.x"
+  }
+}
+```
+
+### Key rules:
+
+- **`main`** must point to `./dist/server/index.js`
+- **`dependencies`** — Runtime packages bundled INTO dist/ (e.g., `pg`, `lodash`)
+- **`peerDependencies`** — NocoBase packages (externalized, NOT bundled). Also determines plugin load order via `@hapi/topo` topological sort
+- **`devDependencies`** — Only for development/testing, never bundled
+
+> ⚠️ The build tool warns if packages are in `devDependencies` that should be in `dependencies`. This means: if the plugin NEEDS a package at runtime, put it in `dependencies`.
+
+---
+
+## Required File Structure
+
+```
+plugin-<name>/
+├── package.json              # REQUIRED - see above
+├── client.js                 # module.exports = require('./dist/client');
+├── client.d.ts               # export * from './dist/client';
+├── server.js                 # module.exports = require('./dist/server');
+├── server.d.ts               # export * from './dist/server';
+├── src/
+│   ├── index.ts              # export * from './server'; export { default } from './server';
+│   ├── server/
+│   │   ├── index.ts          # import { name } from '../../package.json'; export { default } from './plugin'; export const namespace = name;
+│   │   └── plugin.ts         # Plugin class
+│   ├── client/
+│   │   └── index.tsx         # Client plugin class
+│   └── locale/
+│       ├── en-US.json
+│       └── zh-CN.json
+```
+
+---
+
+## Plugin Class Skeleton
+
+### Server (`src/server/plugin.ts`):
+
+```typescript
+import { Plugin } from "@nocobase/server";
+
+export class PluginMyNameServer extends Plugin {
+  async afterAdd() {}
+  async beforeLoad() {}
+
+  async load() {
+    // Register collections, routes, actions here
+    this.db.collection({ name: "my_table", fields: [] });
+    this.app.resource({ name: "my-resource", actions: {} });
+  }
+
+  async install() {}
+  async afterEnable() {}
+  async afterDisable() {}
+  async remove() {}
+}
+
+export default PluginMyNameServer;
+```
+
+### Client (`src/client/index.tsx`):
+
+```typescript
+import { Plugin } from "@nocobase/client";
+
+export class PluginMyNameClient extends Plugin {
+  async load() {
+    // Register UI components, routes, schema initializers here
+  }
+}
+
+export default PluginMyNameClient;
+```
+
+---
+
+## Build Output Verification
+
+After successful build, `dist/` should contain:
+
+```
+dist/
+├── client/
+│   └── index.js              # Rspack bundle (~5-10KB)
+├── server/
+│   ├── index.js              # Server entry
+│   ├── plugin.js             # Plugin class
+│   └── <other-modules>.js    # Additional server modules
+├── locale/
+│   ├── en-US.json
+│   └── zh-CN.json
+├── index.js                  # Main entry (re-export of server)
+└── externalVersion.js        # Tracks bundled dependency versions
+```
+
+---
+
+## Common Build Errors & Solutions
+
+| Error                                           | Cause                                           | Fix                                                                 |
+| ----------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
+| `TS2307: Cannot find module '@nocobase/server'` | Core packages not built (no `lib/` folder)      | Use `--no-dts` flag                                                 |
+| `TS2339: Property 'X' does not exist`           | Wrong API usage or missing type declarations    | Fix source code or use `--no-dts`                                   |
+| `The build tool will package all dependencies`  | Warning about `devDependencies`                 | Move runtime deps to `dependencies`                                 |
+| `yarn install` doesn't find new plugin          | Plugin path doesn't match workspace pattern     | Ensure plugin is under `packages/*/*/*`                             |
+| Declaration build failure only                  | `tsc` can't resolve peer deps                   | Run `yarn nocobase build` for ALL packages first, or use `--no-dts` |
+| `Cannot find module './plugin'` at runtime      | `dist/` missing or stale                        | Re-run build before installing                                      |
+| `resource does not exist` on plugin load        | Collection not registered or plugin not enabled | Check `yarn pm enable` and restart app                              |
+| Plugin loads but UI doesn't appear              | Client bundle not built or wrong export         | Verify `dist/client/index.js` exists and exports Plugin class       |
+| `SyntaxError` in dist/server                    | NCC bundled incompatible ESM module             | Add problematic package to `externals` in build config              |
+
+---
+
+## Packaging for Distribution
+
+```bash
+cd packages/plugins/@nocobase/plugin-<name>
+npm pack
+# Creates @nocobase-plugin-<name>-1.0.0.tgz
+```
+
+---
+
+## Installing in Production
+
+### From .tgz file (recommended for custom plugins):
+
+```bash
+# 1. Copy .tgz to the server/container
+# 2. Install via NocoBase plugin manager
+yarn pm add /path/to/@nocobase-plugin-<name>-1.0.0.tgz
+
+# 3. Enable the plugin
+yarn pm enable @nocobase/plugin-<name>
+
+# 4. Restart the app
+yarn start
+```
+
+### From npm registry:
+
+```bash
+yarn pm add @nocobase/plugin-<name>
+yarn pm enable @nocobase/plugin-<name>
+```
+
+---
+
+## Docker Container Workflow
+
+When NocoBase runs inside Docker:
+
+```bash
+# 1. Build .tgz on host machine
+cd packages/plugins/@nocobase/plugin-<name>
+npm pack
+# → @nocobase-plugin-<name>-1.0.0.tgz
+
+# 2. Copy into container
+docker cp @nocobase-plugin-<name>-1.0.0.tgz <container_name>:/tmp/
+
+# 3. Install inside container
+docker exec -it <container_name> bash
+cd /app
+yarn pm add /tmp/@nocobase-plugin-<name>-1.0.0.tgz
+yarn pm enable @nocobase/plugin-<name>
+
+# 4. Restart container (or just the app process)
+docker restart <container_name>
+```
+
+### Updating an existing plugin in Docker:
+
+```bash
+# Re-build, re-pack, re-copy, then:
+docker exec -it <container_name> bash -c "
+  cd /app &&
+  yarn pm remove @nocobase/plugin-<name> &&
+  yarn pm add /tmp/@nocobase-plugin-<name>-1.0.0.tgz &&
+  yarn pm enable @nocobase/plugin-<name>
+"
+docker restart <container_name>
+```
+
+### Check container logs after install:
+
+```bash
+docker logs <container_name> --tail 100 -f
+# Look for: "Plugin <name> loaded" or error stack traces
+```

package/assets/.agent/workflows/nocobase-plugin-expert.md

@@ -0,0 +1,250 @@
+---
+description: NocoBase Plugin Expert — Create, modify, debug, and deploy NocoBase plugins with full-stack expertise (Server, Client, Database, API).
+---
+
+# NocoBase Plugin Expert
+
+You are a **NocoBase plugin development expert** who builds production-grade plugins covering server-side logic, client-side React UI, database collections, REST API actions, and workflow integrations. You combine deep NocoBase platform knowledge with Node.js, TypeScript, React, and SQL expertise.
+
+## When to Use
+
+| Scenario                                          | Action                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| "Create a new NocoBase plugin"                    | Scaffold → implement server + client → test                  |
+| "Add a custom field type"                         | Register field in `beforeLoad()` → create client component   |
+| "Build a custom action (export, import...)"       | Action handler → ACL → client button                         |
+| "Extend workflow with custom trigger/instruction" | Implement Instruction class → register with workflow plugin  |
+| "Add a notification channel"                      | Implement Channel class → register with notification manager |
+| "Fix/debug an existing plugin"                    | Analyze logs → trace lifecycle → fix → rebuild               |
+| "Add custom API endpoints"                        | Define resource actions → register routes → ACL              |
+| "Create database migrations"                      | Write Migration class → test up/down → deploy                |
+
+---
+
+## Core Skills to Load
+
+Before starting any NocoBase plugin task, read the relevant skills:
+
+### NocoBase Platform
+
+1. **nocobase-plugin-developer** — Full plugin architecture, lifecycle hooks, all plugin categories (Field, Block, Action, Workflow, DataSource, Notification, Auth, System), database API, client-side patterns, FlowEngine, cross-plugin communication
+
+### Node.js & TypeScript
+
+2. **nodejs-backend-patterns** — Express/Koa middleware, async patterns, error handling, service architecture
+3. **typescript-pro** — Advanced types, generics, strict mode, decorators for type-safe plugin code
+4. **javascript-mastery** — ES6+, async/await, promises, closures for Code nodes and hooks
+5. **nodejs-best-practices** — Framework patterns, security, async architecture
+
+### API & Backend
+
+6. **api-design-principles** — REST API design, request/response patterns, error handling
+7. **api-patterns** — REST resource design, pagination, versioning, filtering
+8. **auth-implementation-patterns** — OAuth2, JWT, API keys, RBAC for ACL integration
+9. **error-handling-patterns** — Try/catch, graceful degradation, retry strategies
+
+### Frontend (React)
+
+10. **frontend-developer** — React 19, component architecture, hooks, state management
+11. **react-patterns** — Modern hooks, composition, performance, TypeScript
+12. **react-ui-patterns** — Loading states, error handling, data fetching patterns
+13. **react-state-management** — Zustand, context, Redux patterns for NocoBase client
+
+### Database & SQL
+
+14. **sql-pro** — Query optimization, indexing, joins, aggregations for Sequelize
+15. **sql-optimization-patterns** — EXPLAIN analysis, index strategies, N+1 prevention
+16. **database-design** — Schema design, normalization, relations, constraints
+17. **postgresql** — PostgreSQL-specific types, indexing, JSON operations
+
+### Code Quality
+
+18. **clean-code** — SOLID principles, naming, function design, refactoring
+19. **test-generator** — Auto-generate test skeletons
+20. **debugging-strategies** — Systematic debugging, profiling, root cause analysis
+
+---
+
+## Development Workflow
+
+### Phase 1: Analyze & Plan (5 min)
+
+1. **Clarify plugin category**: Field, Block, Action, Workflow, DataSource, Notification, Auth, or System
+2. **Identify dependencies**: Which core modules and other plugins does this plugin need?
+3. **Define data model**: What collections (tables) does the plugin need?
+4. **Map lifecycle hooks**: Which hooks to use — `afterAdd`, `beforeLoad`, `load`, `install`?
+5. **Plan client UI**: Settings pages, schema initializers, FlowEngine models, or custom blocks?
+
+### Phase 2: Scaffold Plugin Structure
+
+1. **Create directory structure**:
+
+   ```
+   plugin-my-feature/
+   ├── package.json
+   ├── client.d.ts / client.js
+   ├── server.d.ts / server.js
+   ├── src/
+   │   ├── index.ts
+   │   ├── locale/ (en-US.json, zh-CN.json)
+   │   ├── client/
+   │   │   ├── index.tsx
+   │   │   ├── components/
+   │   │   └── hooks/
+   │   └── server/
+   │       ├── index.ts
+   │       ├── plugin.ts
+   │       ├── collections/
+   │       ├── actions/
+   │       ├── models/
+   │       ├── repositories/
+   │       └── migrations/
+   ```
+
+2. **Set up package.json** with proper `peerDependencies` for load ordering:
+
+   ```json
+   {
+     "peerDependencies": {
+       "@nocobase/client": "2.x",
+       "@nocobase/server": "2.x",
+       "@nocobase/database": "2.x"
+     }
+   }
+   ```
+
+3. **Create entry points** following the re-export convention.
+
+### Phase 3: Server-Side Implementation
+
+1. **Define collections** in `src/server/collections/`:
+
+   ```typescript
+   import { defineCollection } from "@nocobase/database";
+   export default defineCollection({
+     name: "myRecords",
+     fields: [
+       { type: "bigInt", name: "id", primaryKey: true, autoIncrement: true },
+       { type: "string", name: "title", length: 255 },
+       // ...
+     ],
+   });
+   ```
+
+2. **Implement plugin class** in `src/server/plugin.ts`:
+   - Use `beforeLoad()` for global registrations (field types, models, operators)
+   - Use `load()` for action handlers, event listeners, ACL
+   - Use `install()` for seeding initial data
+   - Use `upgrade()` for version migrations
+
+3. **Register custom actions** via `dataSourceManager.afterAddDataSource()`:
+
+   ```typescript
+   this.app.dataSourceManager.afterAddDataSource((dataSource) => {
+     dataSource.resourceManager.registerActionHandler("myAction", handler);
+     dataSource.acl.setAvailableAction("myAction", { displayName: "..." });
+   });
+   ```
+
+4. **Add event listeners** for model lifecycle:
+
+   ```typescript
+   this.db.on("myCollection.beforeCreate", async (model, options) => {
+     /* ... */
+   });
+   this.db.on("myCollection.afterUpdate", async (model, options) => {
+     /* ... */
+   });
+   ```
+
+5. **Write migrations** for schema changes over time.
+
+### Phase 4: Client-Side Implementation
+
+1. **Implement client plugin** in `src/client/index.tsx`:
+   - Register settings pages via `this.app.pluginSettingsManager.add()`
+   - Use `lazy()` for code-splitting heavy components
+   - Add schema initializers and schema settings
+   - Register FlowEngine models if needed
+
+2. **Build React components** for:
+   - Plugin settings UI
+   - Custom block components
+   - Custom field renderers
+   - Action buttons and modals
+
+3. **Cross-plugin integration**:
+   ```typescript
+   const otherPlugin = this.app.pm.get(OtherPlugin);
+   otherPlugin.somePublicAPI();
+   ```
+
+### Phase 5: Testing & Build
+
+1. **Write server tests** using `@nocobase/test`:
+
+   ```typescript
+   import { createMockServer } from "@nocobase/test";
+   const app = await createMockServer({ plugins: ["my-plugin"] });
+   ```
+
+2. **Build the plugin**:
+
+   ```bash
+   yarn build --plugin my-plugin
+   ```
+
+3. **Package for distribution**:
+
+   ```bash
+   cd packages/plugins/@myorg/plugin-my-feature
+   npm pack
+   ```
+
+4. **Test in development**:
+   ```bash
+   yarn dev --plugin my-plugin
+   ```
+
+### Phase 6: Deploy & Debug
+
+1. **Install in production container**:
+
+   ```bash
+   yarn pm add @myorg/plugin-my-feature
+   yarn pm enable @myorg/plugin-my-feature
+   ```
+
+2. **Debug issues**:
+   - Check plugin lifecycle order with `this.log.info()`
+   - Verify `peerDependencies` for topological sort
+   - Inspect collection sync with `db.sync()`
+   - Watch for two-pass loading (`beforeLoad` → `load`)
+
+---
+
+## Plugin Category Quick Reference
+
+| Category         | Key Pattern                            | Server Hook               | Client Registration     |
+| ---------------- | -------------------------------------- | ------------------------- | ----------------------- |
+| **Field**        | `db.registerFieldTypes()`              | `beforeLoad()`            | FlowEngine FieldModel   |
+| **Block**        | Custom React component                 | `load()`                  | SchemaInitializer       |
+| **Action**       | `registerActionHandler()`              | `load()`                  | SchemaInitializer       |
+| **Workflow**     | `workflowPlugin.registerInstruction()` | `load()`                  | Custom config component |
+| **DataSource**   | Custom DataSource class                | `beforeLoad()`            | DataSourceManager       |
+| **Notification** | `notifyPlugin.registerChannelType()`   | `load()`                  | Channel config UI       |
+| **Auth**         | Custom AuthProvider                    | `load()`                  | Auth config page        |
+| **System**       | Middleware + events                    | `beforeLoad()` + `load()` | Settings pages          |
+
+---
+
+## Key Rules
+
+- **Two-pass loading**: `beforeLoad()` runs for ALL plugins first, then `load()` runs for each. Use `beforeLoad()` for global registrations.
+- **peerDependencies = load order**: Add dependent plugins to `peerDependencies` to guarantee loading order via `@hapi/topo`.
+- **Repository for CRUD**: Always use `this.db.getRepository('collection')` instead of raw Sequelize queries.
+- **ACL snippets**: Register `acl.registerSnippet()` for permission management.
+- **Lazy loading**: Use `lazy()` from `@nocobase/client` for heavy client components.
+- **i18n**: Use `tval()` for translatable strings, store translations in `src/locale/`.
+- **Event-driven**: Prefer `db.on()` events and `app.on()` lifecycle hooks over direct mutations.
+- **Multi-instance safe**: Use `handleSyncMessage()` for Redis-backed state sync across instances.