@n8n/frontend-module-instance-registry 0.1.0

package/LICENSE.md

@@ -0,0 +1,88 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch (i.e. "master") are not licensed.
+- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a
+	valid n8n Enterprise License specifically allowing you access to such source code files and as defined
+	in "LICENSE_EE.md".
+- All third party components incorporated into the n8n Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,27 @@
+# @n8n/frontend-module-instance-registry
+
+Frontend feature module. Consumed from source by the editor-ui shell through
+`src/app/modules.manifest.ts`; there is no build step and no `dist`.
+
+```bash
+pnpm turbo typecheck --filter=@n8n/frontend-module-instance-registry
+pnpm turbo lint --filter=@n8n/frontend-module-instance-registry
+pnpm turbo test --filter=@n8n/frontend-module-instance-registry
+```
+
+Go through turbo, not `pnpm --filter <pkg> typecheck`: this package is consumed
+from source, and on a cold tree its platform dependencies have not been built
+yet. Turbo builds them first; the bare pnpm form does not.
+
+## Import rules
+
+- Depend on foundation and platform packages only (`@n8n/design-system`,
+  `@n8n/stores`, `@n8n/composables`, `@n8n/i18n`, `@n8n/rest-api-client`,
+  `@n8n/api-types`, `@n8n/frontend-module-sdk`). Never import another
+  `@n8n/frontend-module-*`, and never import `@/…` from the shell.
+- `@n8n/stores` and `@n8n/composables` are **subpath-only** — import
+  `@n8n/stores/settings.store`, not `@n8n/stores`.
+- The no-cross-module rule is currently a convention: the shared tsconfig base
+  omits sibling modules from `paths`, which blocks an accidental import but not
+  a deliberate one (declaring the dependency makes it typecheck clean). The
+  ESLint rule that actually enforces it is CAT-3692.

package/biome.jsonc

@@ -0,0 +1,4 @@
+{
+	"$schema": "../../../../node_modules/@biomejs/biome/configuration_schema.json",
+	"extends": ["../../../../biome.jsonc"]
+}

package/eslint.config.mjs

@@ -0,0 +1,4 @@
+import { defineConfig } from 'eslint/config';
+import { frontendConfig } from '@n8n/eslint-config/frontend';
+
+export default defineConfig(frontendConfig);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@n8n/frontend-module-instance-registry",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "pinia": "^2.2.4",
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.0",
+    "@n8n/api-types": "1.36.0",
+    "@n8n/composables": "1.26.0",
+    "@n8n/frontend-module-sdk": "0.6.0",
+    "@n8n/i18n": "2.36.0",
+    "@n8n/permissions": "0.73.0",
+    "@n8n/design-system": "2.35.0",
+    "@n8n/rest-api-client": "2.36.0",
+    "@n8n/stores": "2.36.0",
+    "n8n-workflow": "2.36.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/vue": "^8.1.0",
+    "@vitejs/plugin-vue": "^5.2.4",
+    "eslint": "9.29.0",
+    "typescript": "6.0.2",
+    "unplugin-icons": "^23.0.1",
+    "vite": "^8.0.2",
+    "vitest": "^4.1.9",
+    "vue-tsc": "^2.2.8",
+    "@n8n/eslint-config": "0.0.1",
+    "@n8n/frontend-vite-config": "0.1.0",
+    "@n8n/playwright-janitor": "0.1.0",
+    "@n8n/typescript-config": "1.10.0",
+    "@n8n/vitest-config": "1.21.0"
+  },
+  "license": "LicenseRef-n8n-sustainable-use",
+  "scripts": {
+    "clean": "rimraf .turbo",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "test:changed": "janitor test-scoped",
+    "test:dev": "vitest",
+    "lint": "eslint src --quiet",
+    "lint:fix": "eslint src --fix",
+    "format": "biome format --write . && prettier --write . --ignore-path ../../../../.prettierignore",
+    "format:check": "biome ci . && prettier --check . --ignore-path ../../../../.prettierignore"
+  }
+}

package/src/__tests__/setup.ts

@@ -0,0 +1,12 @@
+// The shared jsdom harness — observers, matchMedia, canvas, timers, teardown guards.
+import '@n8n/vitest-config/setup/frontend';
+
+import { createPinia, setActivePinia } from 'pinia';
+import { beforeEach } from 'vitest';
+
+// Framework boot stays per-package on purpose: `@n8n/i18n` devDepends on
+// `@n8n/vitest-config`, so booting i18n from inside the shared harness would
+// close a turbo build cycle. Add `useI18n` boot here if this module needs it.
+beforeEach(() => {
+	setActivePinia(createPinia());
+});

package/src/index.ts

@@ -0,0 +1,5 @@
+// The module's only public entry. The shell imports the descriptor from here via
+// `modules.manifest.ts`; anything else the shell (or a test) needs must be exported
+// here too — deep paths into `src/` are not part of the contract.
+export { InstanceRegistryModule } from './instance-registry.module';
+export { useInstanceRegistryStore } from './instance-registry.store';

package/src/instance-registry.module.ts

@@ -0,0 +1,15 @@
+import type { FrontendModuleDescription } from '@n8n/frontend-module-sdk';
+
+/**
+ * Store-only: this module contributes no UI surface, so registering it is a no-op —
+ * `moduleInitializer` guards every surface it reads. `AboutModal` and `useDebugInfo`
+ * consume the store directly; the descriptor is what makes this a module the shell
+ * knows about rather than a library it happens to import.
+ */
+export const InstanceRegistryModule: FrontendModuleDescription = {
+	// Must match the backend module id: both gate off `/rest/module-settings`.
+	id: 'instance-registry',
+	name: 'Instance Registry',
+	description: 'Reports which instances are in this deployment and their health',
+	icon: 'server',
+};

package/src/instance-registry.store.test.ts

@@ -0,0 +1,67 @@
+import type { ClusterInfoResponse } from '@n8n/api-types';
+import { setActivePinia, createPinia } from 'pinia';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { useInstanceRegistryStore } from './instance-registry.store';
+
+const mocks = vi.hoisted(() => ({
+	getClusterInfo: vi.fn(),
+}));
+
+vi.mock('@n8n/rest-api-client/api/instance-registry', () => ({
+	getClusterInfo: mocks.getClusterInfo,
+}));
+
+vi.mock('@n8n/stores/useRootStore', () => ({
+	useRootStore: () => ({
+		restApiContext: { baseUrl: 'http://localhost', sessionId: 'test' },
+	}),
+}));
+
+const SAMPLE_RESPONSE: ClusterInfoResponse = {
+	instances: [
+		{
+			schemaVersion: 1,
+			instanceKey: 'main-1',
+			hostId: 'host-a',
+			instanceType: 'main',
+			instanceRole: 'leader',
+			version: '1.110.0',
+			registeredAt: 0,
+			lastSeen: 0,
+		},
+	],
+	checks: {},
+};
+
+describe('useInstanceRegistryStore', () => {
+	beforeEach(() => {
+		setActivePinia(createPinia());
+		mocks.getClusterInfo.mockReset();
+	});
+
+	it('fetches and stores cluster info', async () => {
+		mocks.getClusterInfo.mockResolvedValue(SAMPLE_RESPONSE);
+
+		const store = useInstanceRegistryStore();
+		await store.fetchClusterInfo();
+
+		expect(mocks.getClusterInfo).toHaveBeenCalledTimes(1);
+		expect(store.clusterInfo).toEqual(SAMPLE_RESPONSE);
+		expect(store.isAvailable).toBe(true);
+	});
+
+	it('swallows errors and preserves the prior snapshot', async () => {
+		mocks.getClusterInfo.mockResolvedValueOnce(SAMPLE_RESPONSE);
+		mocks.getClusterInfo.mockRejectedValueOnce(new Error('endpoint failure'));
+		const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+		const store = useInstanceRegistryStore();
+		await store.fetchClusterInfo();
+		await store.fetchClusterInfo();
+
+		expect(store.clusterInfo).toEqual(SAMPLE_RESPONSE);
+		expect(debugSpy).toHaveBeenCalled();
+		debugSpy.mockRestore();
+	});
+});

package/src/instance-registry.store.ts

@@ -0,0 +1,29 @@
+import type { ClusterInfoResponse } from '@n8n/api-types';
+import * as instanceRegistryApi from '@n8n/rest-api-client/api/instance-registry';
+import { useRootStore } from '@n8n/stores/useRootStore';
+import { defineStore } from 'pinia';
+import { computed, ref } from 'vue';
+
+export const useInstanceRegistryStore = defineStore('instanceRegistry', () => {
+	const rootStore = useRootStore();
+
+	const clusterInfo = ref<ClusterInfoResponse | null>(null);
+
+	const isAvailable = computed(() => clusterInfo.value !== null);
+
+	async function fetchClusterInfo(): Promise<void> {
+		try {
+			clusterInfo.value = await instanceRegistryApi.getClusterInfo(rootStore.restApiContext);
+		} catch (error) {
+			// Leave the previous snapshot in place on transient network errors — debug
+			// generation must never fail because cluster info couldn't be fetched.
+			console.debug('Failed to fetch instance registry cluster info', error);
+		}
+	}
+
+	return {
+		clusterInfo,
+		isAvailable,
+		fetchClusterInfo,
+	};
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"extends": "@n8n/typescript-config/tsconfig.frontend-module.json",
+	"compilerOptions": {
+		// `rootDirs`, `types` and `include` cannot be inherited from the base: relative entries in
+		// them resolve against this file, so a copy in the base would point at the base's directory.
+		// (`paths` is the exception and does come from the base.)
+		"rootDirs": [".", "../../../frontend/@n8n/design-system/src"],
+		// The two `.d.ts` entries are ambient declarations this package never imports, so nothing
+		// pulls them into the program: `~icons/*` and `markdown-it-task-lists` for design-system's
+		// source, `window.BASE_PATH` for `@n8n/stores`'s. Consuming those packages from source is
+		// what makes them the consumer's problem — a built `dist` would have carried them.
+		"types": [
+			"vite/client",
+			"vitest/globals",
+			"unplugin-icons/types/vue",
+			"../../../frontend/@n8n/design-system/src/shims-modules.d.ts",
+			"../../../frontend/@n8n/stores/src/shims.d.ts"
+		]
+	},
+	"include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,23 @@
+import vue from '@vitejs/plugin-vue';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { defineConfig, mergeConfig } from 'vite';
+import { frontendAliases } from '@n8n/frontend-vite-config';
+import { vitestConfig } from '@n8n/vitest-config/frontend';
+
+const packageDir = fileURLToPath(new URL('.', import.meta.url));
+const packagesDir = resolve(packageDir, '..', '..', '..');
+
+export default mergeConfig(
+	defineConfig({
+		plugins: [vue()],
+		resolve: {
+			// The same platform mapping the editor-ui dev server uses, so a test resolves
+			// `@n8n/stores/...` from source rather than from a stale `dist` — the two disagreeing is
+			// what put 1,111 specifiers on the wrong side of the src/dist line. Sibling modules are
+			// deliberately absent: nothing here should make a cross-module import resolve.
+			alias: frontendAliases(packagesDir),
+		},
+	}),
+	vitestConfig,
+);