@n8n/node-cli 0.22.0 → 0.23.1

package/dist/template/templates/shared/default/.agents/properties.md

@@ -0,0 +1,174 @@
+# Properties, expressions, and dynamic options
+
+## Expressions
+Parameter values can be expressions when they start with `=`. Everything
+inside `{{ ... }}` is evaluated as JavaScript. Common (but not all)
+special variables:
+- `$value` - the value of the current parameter
+- `$parameter` - object with all of the parameter values (key = name)
+- `$credentials` - object with all of the credential values
+
+## displayOptions
+You can show or hide parameters based on other parameters using `displayOptions`:
+```typescript
+{
+  // ...
+  displayOptions: {
+    show: {
+      // show this parameter when parameter `inputMode` has value of `'json'`
+      inputMode: ['json'],
+    },
+  },
+}
+```
+Using condition:
+```typescript
+{
+  // ...
+  displayOptions: {
+    show: {
+      // show this parameter when parameter `inputMode` ends with `'json'`
+      inputMode: [{ _cnd: { endsWith: 'json' } }],
+    },
+  },
+}
+```
+Hide example:
+```typescript
+{
+  // ...
+  displayOptions: {
+    hide: {
+      // hide this parameter when `resource` is either `'user'` or `'organization'` and `operation` is `'getRepositories'`
+      resource: ['user', 'organization'],
+      operation: ['getRepositories'],
+    },
+  },
+}
+```
+You can also show/hide based on the node's version using `@version`:
+```typescript
+{
+  displayOptions: {
+    show: {
+      // only show for versions earlier than 1.4
+      '@version': [{ _cnd: { lt: 1.4 } }],
+    },
+  },
+}
+```
+
+## Loading dynamic options
+Most properties are entirely defined in the code, but sometimes some
+data needs to be fetched dynamically. For that case, you can use one of:
+
+### loadOptionsMethod
+For `options` / `multiOptions`:
+```typescript
+{
+  displayName: 'Category',
+  name: 'categoryId',
+  type: 'options',
+  typeOptions: {
+    loadOptionsMethod: 'getCategories',
+  },
+  default: '',
+  description: 'Choose a category',
+}
+```
+Node class:
+```typescript
+methods = {
+  loadOptions: {
+    async getCategories(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]> {
+      // Make an API call and return an array of { name, value }
+      return [];
+    },
+  },
+};
+```
+
+### resourceLocator
+Used when the user can either choose from a list or specify an ID manually:
+```typescript
+{
+  displayName: 'Tool',
+  name: 'tool',
+  type: 'resourceLocator',
+  default: { mode: 'list', value: '' },
+  required: true,
+  description: 'The tool to use',
+  modes: [
+    {
+      displayName: 'From List',
+      name: 'list',
+      type: 'list',
+      typeOptions: {
+        searchListMethod: 'getTools',
+        searchable: true,
+      },
+    },
+    {
+      displayName: 'ID',
+      name: 'id',
+      type: 'string',
+    },
+  ],
+}
+```
+Node class:
+```typescript
+methods = {
+  listSearch: {
+    async getTools(this: ILoadOptionsFunctions) {
+      // Return items suitable for a searchable list
+    },
+  },
+};
+```
+
+### resourceMapper
+Use when the **schema is dynamic**, e.g. Google Sheets, where columns
+can change:
+```typescript
+{
+  displayName: 'Parameters',
+  name: 'parameters',
+  type: 'resourceMapper',
+  default: {
+    mappingMode: 'defineBelow',
+    value: null,
+  },
+  noDataExpression: true,
+  required: true,
+  typeOptions: {
+    loadOptionsDependsOn: ['tool.value'],
+    resourceMapper: {
+      resourceMapperMethod: 'getToolParameters',
+      hideNoDataError: true,
+      addAllFields: false,
+      supportAutoMap: false,
+      mode: 'add',
+      fieldWords: {
+        singular: 'parameter',
+        plural: 'parameters',
+      },
+    },
+  },
+  displayOptions: {
+    show: {
+      inputMode: ['manual'],
+    },
+  },
+}
+```
+Node class:
+```typescript
+export async function getToolParameters(
+  this: ILoadOptionsFunctions,
+): Promise<ResourceMapperFields> {
+  // Implementation omitted; build fields based on the external tool
+  return { fields: [] };
+}
+```
+Use `resourceMapper` **only when necessary**, as it is more advanced.

package/dist/template/templates/shared/default/.agents/versioning.md

@@ -0,0 +1,90 @@
+# Versioning
+
+## Overview
+Nodes have versions, defined in the `version` property:
+- If the node has only one version -> `version: 1`
+- If the node supports **light versioning** -> `version: [1, 1.1, 1.2]`
+  etc.
+
+Use versioning when you make **breaking changes** that should not alter
+the behavior of existing workflows.
+
+## Checking version in code
+```typescript
+async execute(this: IExecuteFunctions) {
+    const version = this.getNode().typeVersion;
+    if (version >= 1.1) {
+        // v1.1+ behavior
+    } else {
+        // v1 behavior
+    }
+}
+```
+
+## Full versioning
+For more complex changes, nodes can extend `VersionedNodeType`, where
+each "full" version is a separate implementation. This is called **full
+versioning** and is **only supported for programmatic-style nodes**:
+```typescript
+// If.node.ts
+export class If extends VersionedNodeType {
+  constructor() {
+    const baseDescription: INodeTypeBaseDescription = {
+      displayName: 'If',
+      name: 'if',
+      icon: 'fa:map-signs',
+      iconColor: 'green',
+      group: ['transform'],
+      description: 'Route items to different branches (true/false)',
+      defaultVersion: 2.3,
+    };
+
+    const nodeVersions: IVersionedNodeType['nodeVersions'] = {
+      1: new IfV1(baseDescription),
+      2: new IfV2(baseDescription),
+      2.1: new IfV2(baseDescription),
+      2.2: new IfV2(baseDescription),
+      2.3: new IfV2(baseDescription),
+    };
+
+    super(nodeVersions, baseDescription);
+  }
+}
+
+// IfV1.node.ts
+export class IfV1 implements INodeType {
+  description: INodeTypeDescription;
+
+  constructor(baseDescription: INodeTypeBaseDescription) {
+    this.description = {
+      ...baseDescription,
+      version: 1,
+      defaults: {
+        name: 'If',
+        color: '#408000',
+      },
+      inputs: [NodeConnectionTypes.Main],
+      outputs: [NodeConnectionTypes.Main, NodeConnectionTypes.Main],
+      outputNames: ['true', 'false'],
+      properties: [
+        // ...
+      ],
+    };
+  }
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    // ...
+  }
+}
+```
+
+## Important rules
+- **Declarative-style nodes do not support full versioning**, only light
+  versioning
+- Do **not** introduce full versioning unless:
+  - The node already uses it, or
+  - You are explicitly asked to add a new full version, or
+  - You're doing a complete **rewrite** of the node from scratch and it
+    has different resources/operations compared to last version
+- **Do NOT** introduce full versioning when writing the very first
+  version of the node

package/dist/template/templates/shared/default/.agents/workflow.md

@@ -0,0 +1,97 @@
+# Workflow
+
+## How to work on this project
+When asked to build or update a node in this project, follow these steps:
+
+1. Clarify the requirements. Ask for (if not already provided):
+   - Which resources and operations the node needs to have
+   - The authentication method (API key, OAuth2, etc)
+   - Example use case or sample payloads, if available
+   Do this **only** if there are multiple options **after** gathering
+   information and you are not sure which to pick
+2. Decide on the node style (declarative vs programmatic):
+   - Prefer declarative-style nodes when:
+     - The integration is mostly simple HTTP/REST requests and responses
+     - You can express this behavior by mapping parameters to
+       URL/query/body/headers
+   - Use programmatic-style nodes only when you have at least one of:
+     - Multiple dependent API calls are needed per execution
+     - Complex control flow or aggregation
+     - Responses require heavy transformation that can't be described
+       declaratively
+   - If you choose programmatic-style, briefly explain **why**
+     declarative-style won't work for this particular node
+3. Plan before coding:
+   - Outline what description the node will have, its resources and
+     operations
+   - Which credentials the node will use and their properties
+   - Confirm the plan, if you are not given one and are generating it
+   - **Never start coding without a plan**
+4. Implement. Create or update:
+   - The node files (`nodes/<n>/<n>.node.ts`)
+   - The credentials files (`credentials/<n>.credentials.ts`)
+   - Other files with helpers and extracted functions/classes
+   - `package.json` (`n8n.nodes` and `n8n.credentials` entries)
+5. Quality checks:
+   - Build the project to ensure it actually builds
+   - Run the linter to make sure that there aren't any warnings or
+     errors
+   - Ensure UX follows the [n8n UX guidelines](https://docs.n8n.io/integrations/creating-nodes/build/reference/ux-guidelines/)
+   - Ensure the credentials are secure (sensitive values **are marked as
+     `password`**, **no secrets logged** and **there aren't any
+     hardcoded secrets**)
+   - Run the project, so that the user can manually verify that it works.
+     Ask the user on how to run it, and if something goes wrong tell
+     them to run it themselves
+6. Iterate on the code, if needed, going through the process again:
+   - Plan
+   - Implement
+   - Verify
+
+## Development guidelines
+- Use the `n8n-node` CLI tool **whenever possible**, so for stuff like building
+  a node, using dev mode with hot-reload linting, etc. Using this tool is the
+  best way to make sure the code is of high quality and complies with n8n's
+  standards
+- **Always** make sure to address any lint/typecheck errors/warnings, unless
+  there is a **very specific reason** to ignore/disable it. Linter is your best
+  friend to make sure the code is of high quality and complies with n8n's
+  standards
+- Before making any changes to the code, make sure you've gathered all required
+  context and **planned out** what you're going to do. If the plan looks good,
+  make sure to stick to it to ensure the code you produce is doing what the
+  user expects
+- After making changes verify that there are no lint/typecheck issues. Also
+  allow the user to manually test the node in n8n to verify that it does what
+  is expected
+- Make sure to use **proper types whenever possible**
+- If you are updating the npm package version, make sure to **update
+  CHANGELOG.md** in the root of the repository
+
+## CLI
+This project uses n8n's CLI tool for developing community nodes: `n8n-node`. It
+is available as a dev dependency and `package.json` has some aliases for common
+commands. Short overview of the commands:
+- `n8n-node dev` - run n8n with your node in development mode with hot reload.
+  This command starts up n8n on `http://localhost:5678` so that the user can
+  manually test the node. It also links it to n8n's custom nodes directory
+  (`~/.n8n-node-cli/.n8n/custom` by default), so it's available within n8n.
+  `--external-n8n` makes it not launch n8n and `--custom-user-folder <path>`
+  can be used to specify the folder where user-specific data is stored
+  (`~/.n8n-node-cli` is the default)
+- `n8n-node build` - compile your node and prepare it for distribution.
+- `n8n-node lint` - lint the node in the current directory.
+  Use `--fix` flag to automatically fix fixable issues.
+- `n8n-node cloud-support` - manage n8n Cloud eligibility.
+  If invoked without arguments, show current cloud support status. Invoke
+  `n8n-node cloud-support enable` to enable strict mode + default ESLint config
+  or `n8n-node cloud-support disable` to allow custom ESLint config (disables
+  cloud eligibility)
+- `n8n-node release` - publish your community node package to npm.
+  This command handles the complete release process using `release-it`:
+  - Builds the node
+  - Runs linting checks
+  - Updates changelog
+  - Creates git tags
+  - Creates GitHub releases
+  - Publishes to npm

package/dist/template/templates/shared/default/AGENTS.md

@@ -0,0 +1,102 @@
+# n8n community node
+
+## Overview
+This is a project containing code for an n8n community node. n8n is a workflow
+automation platform where users build workflows with nodes, which are the
+building block of a workflow. Nodes can perform a range of actions, such as
+starting a workflow (called a "trigger node"), fetching and sending data, or
+processing and manipulating it. Besides that there are credentials - entities
+that store sensitive information on how to connect to external services and
+APIs. A node can require some credentials to be used. Community nodes are a way
+for anyone to create such nodes and add them to be used in n8n. All community
+nodes are named in a format: `n8n-nodes-<n>` or `@org/n8n-nodes-<n>`.
+Community nodes can also be submitted for approval to be used on n8n Cloud
+version. In that case there are rules that the node needs to follow in order to
+be approved
+
+## Important notes
+- Follow the **rules and guidelines in this document and the linked docs
+  below** over any code examples.
+- All code blocks in these docs are **illustrative and incomplete**.
+  They **MUST NOT** be copied verbatim or assumed to be the final desired code.
+- Replace example names like `Example`, `Wordpress`, `wordpressApi`, etc.
+  with names that match the **actual service / node** you are building.
+- When in doubt, **generalize from the patterns**, don't replicate the exact
+  structure, fields, or values from the examples.
+- Produce the **full implementation** needed for the current project
+  (nodes, credentials, tests, etc.), not just fragments similar to examples.
+- If an example omits parts (e.g. types, operations, properties), **infer and
+  implement the missing parts** based on the real requirements / API docs.
+- Never output `Wordpress`-specific code unless the project is actually about
+  WordPress.
+
+## Project structure
+There are two main folders in this project:
+- `nodes` contains all of the nodes in a package (there can be more than 1).
+  The code for each node usually lives in its own folder
+- `credentials` contains all of the credentials in a package. Usually it's just
+  a single file for every credential
+So it looks something like this:
+.
+├── nodes/
+│   └── Example/
+│       ├── Example.node.ts
+│       └── ...
+├── credentials/
+│   └── Example.credentials.ts
+├── package.json
+└── ...
+It's important to note that `package.json` has a special field `n8n` that have
+information about nodes and credentials in a package:
+```json
+{
+  "name": "n8n-nodes-example",
+  "version": "1.0.0",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "strict": true,
+    "credentials": [
+        "dist/credentials/Example.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/Example/Example.node.js"
+    ]
+  }
+}
+```
+`nodes` and `credentials` keys contain paths to transpiled JS files in a `dist`
+folder for the nodes and credentials respectively. If you add/remove/rename
+nodes and/or credentials, you need to make sure to update `n8n.nodes` and
+`n8n.credentials` keys in `package.json` accordingly. Initial files in the
+project _may_ contain example nodes and/or credentials that need to be
+**removed or renamed** once you start making an actual node.
+
+## Key guidelines
+- Use the `n8n-node` CLI tool **whenever possible** for building, dev mode,
+  linting, etc.
+- **Always** address any lint/typecheck errors/warnings, unless there is a
+  **very specific reason** to ignore/disable it
+- Make sure to use **proper types whenever possible**
+- If you are updating the npm package version, make sure to **update
+  CHANGELOG.md** in the root of the repository
+- Read `.agents/workflow.md` for more info
+
+## Context-specific docs
+Load these before working on the relevant area:
+
+| Working on...                        | Read first                                                          |
+|--------------------------------------|---------------------------------------------------------------------|
+| Any node file in `nodes/`            | `.agents/nodes.md` and `.agents/properties.md`                      |
+| A declarative-style node             | above + `.agents/nodes-declarative.md`                              |
+| A programmatic-style node            | above + `.agents/nodes-programmatic.md`                             |
+| Files in `credentials/`              | `.agents/credentials.md`                                            |
+| Adding a new version to a node       | `.agents/versioning.md`                                             |
+| Starting a new task or planning      | `.agents/workflow.md`                                               |
+
+## Additional resources
+If you need any extra information, here are links to n8n's official docs
+regarding building community nodes:
+- https://docs.n8n.io/integrations/community-nodes/build-community-nodes/
+- https://docs.n8n.io/integrations/creating-nodes/overview/
+- https://docs.n8n.io/integrations/creating-nodes/build/reference/
+- https://docs.n8n.io/integrations/creating-nodes/build/reference/ux-guidelines/

package/dist/template/templates/shared/default/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n/node-cli",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Official CLI for developing community nodes for n8n",
   "bin": {
     "n8n-node": "bin/n8n-node.mjs"
@@ -14,8 +14,8 @@
   "files": [
     "bin",
     "dist",
-    "LICENSE_EE.md",
-    "LICENSE.md"
+    "LICENSE.md",
+    "LICENSE_EE.md"
   ],
   "repository": {
     "type": "git",
@@ -45,8 +45,8 @@
     "rimraf": "6.0.1",
     "ts-morph": "^27.0.2",
     "typescript-eslint": "^8.35.0",
-    "@n8n/eslint-plugin-community-nodes": "0.8.0",
-    "@n8n/ai-node-sdk": "0.3.0"
+    "@n8n/ai-node-sdk": "0.4.1",
+    "@n8n/eslint-plugin-community-nodes": "0.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",