Skip to content

Ship all JavaScript adapters in one npm package - #1070

Open
zlareb1 wants to merge 3 commits into
mainfrom
refactor/single-npm-package
Open

zlareb1 wants to merge 3 commits into
mainfrom
refactor/single-npm-package

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Related: #1076

Changelog category (leave one):

  • Build/Testing/Packaging Improvement

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

The @clickhouse/loom npm package includes the native n8n nodes and credentials alongside the TypeScript SDK and its framework adapters. Self-hosted n8n loads the nodes through N8N_CUSTOM_EXTENSIONS.

Why

All JavaScript integrations need one package version and one publication path. A separate n8n package requires its own registry setup and trusted publisher. The SDK build can include the native files and validate them before its existing publisher uploads the tarball.

The tradeoff is installation through n8n's custom-node directory: its Community Nodes settings installer requires an n8n-nodes- package name. The setup documentation gives the shared-package command. The adapter targets self-hosted n8n.

Scope and risk

Move the n8n source, icons, licenses and behavior tests into the TypeScript SDK. Export the classes through @clickhouse/loom/integrations/n8n and emit the CommonJS files that the native loader expects. Remove the standalone package, its publishing workflow and its unused node-CLI toolchain patch.

n8n-workflow remains an optional host peer. Plain SDK installs gain no required runtime dependencies. The tarball tests check this in a clean consumer, then install a locked n8n host and exercise the native files and both module formats. Separate test installs accommodate the frameworks' different Zod requirements. SDK builds skip dependency lifecycle scripts because the host expression engine is not used by these adapter tests.

The n8n framework keeps its UUID 11.1.1 override when moving into the SDK; a regression test checks that undersized UUID output buffers are rejected.

The artifact grows to include the native bundles. Packaging, module loading and host dependency resolution are the main risks. The sender census classifies history listing, lookup and deletion as identity-bound references and pins their identity builders; message content writes retain their admission class. The release skill, release documentation and publisher contract test record the single-package policy. Generated documentation and the operation reach manifest follow the source move.

Compatibility, rollout and rollback

  • Wire: no operations, fields or defaults change.
  • Operator steps: install @clickhouse/loom in the npm project running n8n, set N8N_CUSTOM_EXTENSIONS to its bundled node directory, and restart each n8n worker. The documentation includes the commands. No migration or backfill is required.
  • Publication: this PR changes the contents of the next SDK release; it does not republish an existing npm version.
  • Rollback: revert the packaging change before publication, or publish a subsequent SDK version after publication. There are no stored-data changes.

Tests

  • make format-check, make lint, make typecheck.
  • npm --prefix sdk/typescript run check and npm --prefix sdk/typescript run check:dist: source tests, README examples, native adapter tests against the packed tarball, publint and declaration resolution.
  • npm exec --yes --package=node@22 -- node scripts/test-n8n.mjs from sdk/typescript: the packed artifact loads and the adapter tests pass on Node 22.
  • Targeted Python tests (636 passed) for the sender census, publication, native tooling, agent instructions, documentation links, public copy, release preparation, operation reach and test inventory pass.
  • pytest tests/unit/test_install_script.py -q: 212 passed, one platform skip. pytest bench -q: 251 passed.
  • The broader local make test-unit run encounters SQL and parser failures. Representative failures reproduce on unchanged main; the local ClickHouse binary does not support the schema's enable_quantized_codec setting. CI runs the full suite on the supported environment.
  • The WSL platform job passes on one rerun after its existing one-second session-close test misses the close request under load.
  • The Windows plugin-platform job passes on one rerun after ENOTEMPTY during test-directory cleanup. The unchanged hook contract test waits for parent hooks but can race detached hook work.
  • A live n8n application and a live Loom server were not started; the artifact tests use real host libraries with a fake HTTP transport.

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated: Codex wrote the packaging changes and checked the artifact contents, adapter behavior, module resolution and generated files with the commands above.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass; the integration suite passes if server behaviour changed. Local full-suite limitations are listed above; CI must pass before merge.
  • Generated files are regenerated in this PR, not by hand.
  • No migrations are added or changed.
  • No coding-agent plugin runtime files change; plugin versions are unchanged.
  • No frontend files change.
  • Docs describe the package and operator steps.
  • Repository text passes the public-copy checks.
  • Commits are signed off.

@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
loom-docs Ready Ready Preview Nov 21, 2026 12:04am UTC

Request Review

@zlareb1
zlareb1 force-pushed the refactor/single-npm-package branch 3 times, most recently from fd8ae44 to 809aa32 Compare November 20, 2026 21:14
@zlareb1
zlareb1 force-pushed the refactor/single-npm-package branch 3 times, most recently from 7cd3371 to dac8e34 Compare November 20, 2026 23:55
Bundle the native n8n nodes in @clickhouse/loom and publish them through the SDK release workflow. Qualify the packed artifact with an isolated n8n host and record the single-package release policy.

Signed-off-by: Lareb Zafar <lareb.zafar@clickhouse.com>
Keep the adapter toolchain on UUID 11.1.1 when moving it into the shared SDK. Check that its UUID helper rejects an undersized output buffer.

Signed-off-by: Lareb Zafar <lareb.zafar@clickhouse.com>
The SDK scan includes the moved n8n history adapter. Review its identity-bound list, get and delete payloads and pin their scope builders without changing content-write admission.

Signed-off-by: Lareb Zafar <lareb.zafar@clickhouse.com>
@zlareb1
zlareb1 force-pushed the refactor/single-npm-package branch from dac8e34 to 8ee5397 Compare November 21, 2026 00:02

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant