thinkwork-cli 0.12.12 → 0.12.15

package/dist/plugins/n8n/test/integrated-app-contract.test.ts

@@ -0,0 +1,353 @@
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  validatePluginManifest,
+  type UiSurfaceComponent,
+} from "@thinkwork/plugin-catalog/contracts";
+import { defineFirstPartyPluginPackage } from "@thinkwork/plugin-catalog/plugin-package";
+
+import {
+  N8N_APP_DESCRIPTION,
+  N8N_APP_DISPLAY_NAME,
+  N8N_APP_ICON,
+  N8N_APP_KEY,
+  N8N_APP_ROUTE_SEGMENT,
+  N8N_APP_SURFACE_KEY,
+  n8nApplicationConfig,
+} from "../n8n-app/src/application-config";
+import {
+  bridgeThreadPath,
+  connectionLabel,
+  executionStatuses,
+  filterN8nExecutions,
+  filterN8nWorkflows,
+  formatDuration,
+  readinessLabel,
+  type N8nAppExecutionRow,
+  type N8nAppWorkflowRow,
+} from "../n8n-app/src/lib/n8n-app-data";
+import { n8nPluginPackage } from "../src/index";
+import { N8N_PLUGIN_VERSION, n8nManifest } from "../src/manifest";
+
+describe("n8n integrated app contract", () => {
+  it("declares a launchable ThinkWork app surface in the n8n manifest", () => {
+    const manifest = validatePluginManifest(n8nManifest);
+    const latestVersion = manifest.versions.find(
+      (version) => version.version === N8N_PLUGIN_VERSION,
+    );
+    if (!latestVersion) throw new Error("Missing latest n8n manifest version");
+
+    const uiSurfaces = latestVersion.components.filter(
+      (component): component is UiSurfaceComponent =>
+        component.type === "ui-surface",
+    );
+    const appSurface = uiSurfaces.find(
+      (component) => component.key === N8N_APP_SURFACE_KEY,
+    );
+
+    expect(appSurface).toEqual({
+      type: "ui-surface",
+      key: N8N_APP_SURFACE_KEY,
+      displayName: N8N_APP_DISPLAY_NAME,
+      intendedMount: "apps.main",
+      launch: {
+        schemaVersion: 1,
+        type: "app",
+        appKey: N8N_APP_KEY,
+        routeSegment: N8N_APP_ROUTE_SEGMENT,
+        mount: "main-shell",
+        runtime: "trusted-bundled-react",
+        description: N8N_APP_DESCRIPTION,
+        icon: N8N_APP_ICON,
+        entitlementProductKey: N8N_APP_KEY,
+      },
+    });
+    expect(uiSurfaces).toContainEqual({
+      type: "ui-surface",
+      key: "package-settings",
+      displayName: "n8n custom package settings",
+      intendedMount: "settings.plugins.detail",
+    });
+  });
+
+  it("keeps the original 0.1.0 manifest payload immutable for pinned installs", () => {
+    const manifest = validatePluginManifest(n8nManifest);
+    const legacyVersion = manifest.versions.find(
+      (version) => version.version === "0.1.0",
+    );
+    if (!legacyVersion) throw new Error("Missing legacy n8n manifest version");
+
+    expect(legacyVersion.components.map((component) => component.type)).toEqual([
+      "infrastructure",
+      "mcp-server",
+      "ui-surface",
+      "skills",
+    ]);
+    expect(
+      legacyVersion.components.some(
+        (component) =>
+          component.type === "ui-surface" &&
+          component.key === N8N_APP_SURFACE_KEY,
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps the app source and auth decision inside the n8n package", () => {
+    const defined = defineFirstPartyPluginPackage(n8nPluginPackage);
+
+    expect(defined.ownedSources).toContainEqual({
+      kind: "web",
+      path: "plugins/n8n/n8n-app",
+      description:
+        "Native ThinkWork n8n installed app surface for workflow and execution operations.",
+    });
+    expect(n8nApplicationConfig).toMatchObject({
+      schemaVersion: 1,
+      appKey: "n8n-workflow-operations",
+      host: {
+        mount: "main-shell",
+        runtime: "trusted-bundled-react",
+        route: "/apps/n8n/workflows",
+        sourceRoot: "plugins/n8n/n8n-app",
+        frontComponent: {
+          source:
+            "src/front-components/thinkwork-workflows.front-component.tsx",
+          exportName: "ThinkWorkN8nWorkflowsApp",
+        },
+      },
+      dataAccess: {
+        mode: "thinkwork-session",
+        boundary: "server-mediated",
+      },
+    });
+    expect(n8nApplicationConfig.dataAccess.allowedCredentials).toEqual([
+      "tenant-service-credential:n8n-mcp-access-token",
+      "tenant-plugin-credential:n8n-api",
+    ]);
+    expect(n8nApplicationConfig.dataAccess.forbidden).toEqual([
+      "browser-entered-api-key",
+      "unauthenticated-proxy",
+      "workflow-publish",
+      "workflow-unpublish",
+      "workflow-activate",
+      "workflow-deactivate",
+      "workflow-delete",
+      "execution-retry",
+      "execution-stop",
+    ]);
+  });
+
+  it("documents and exports the n8n app host boundary", async () => {
+    const readme = await readFile(
+      fileURLToPath(new URL("../n8n-app/README.md", import.meta.url)),
+      "utf8",
+    );
+    const packageJson = await readFile(
+      fileURLToPath(new URL("../n8n-app/package.json", import.meta.url)),
+      "utf8",
+    );
+    const pluginPackageJson = await readFile(
+      fileURLToPath(new URL("../package.json", import.meta.url)),
+      "utf8",
+    );
+    const frontComponent = await readFile(
+      fileURLToPath(
+        new URL(
+          "../n8n-app/src/front-components/thinkwork-workflows.front-component.tsx",
+          import.meta.url,
+        ),
+      ),
+      "utf8",
+    );
+
+    expect(readme).toContain("/apps/n8n/workflows");
+    expect(readme).toContain("does not use `twenty-sdk`");
+    expect(readme).toContain("server-mediated");
+    expect(readme).toContain("ThinkWork APIs");
+    expect(readme).toContain("must not ask users to paste an n8n API key");
+    expect(readme).toContain("activate");
+    expect(readme).toContain("retry");
+    expect(packageJson).toContain('"name": "@thinkwork/n8n-app"');
+    expect(packageJson).toContain('"packageManager": "pnpm@9.15.9"');
+    expect(pluginPackageJson).toContain('"./n8n-app"');
+    expect(pluginPackageJson).toContain('"./n8n-app-data"');
+    expect(frontComponent).toContain("ThinkWorkN8nWorkflowsApp");
+    expect(frontComponent).toContain("WorkflowTable");
+    expect(frontComponent).toContain("ExecutionTable");
+    expect(frontComponent).toContain("nativeWorkflowUrl");
+    expect(frontComponent).toContain("nativeExecutionUrl");
+    expect(frontComponent).not.toContain("twenty-sdk");
+    expect(frontComponent).not.toContain("workflow-publish");
+    expect(frontComponent).not.toContain("execution-retry");
+  });
+
+  it("documents guarded app sync and smoke verification", async () => {
+    const syncScriptPath = fileURLToPath(
+      new URL("../scripts/sync-thinkwork-app.mjs", import.meta.url),
+    );
+    const smokeScriptPath = fileURLToPath(
+      new URL("../smoke/n8n-integrated-app-smoke.mjs", import.meta.url),
+    );
+    const repoRoot = fileURLToPath(new URL("../../..", import.meta.url));
+    const syncScript = await readFile(syncScriptPath, "utf8");
+    const smokeScript = await readFile(smokeScriptPath, "utf8");
+    const runbook = await readFile(
+      fileURLToPath(
+        new URL(
+          "../../../docs/runbooks/n8n-thinkwork-native-app-install.md",
+          import.meta.url,
+        ),
+      ),
+      "utf8",
+    );
+    const smokeReadme = await readFile(
+      fileURLToPath(new URL("../smoke/README.md", import.meta.url)),
+      "utf8",
+    );
+    const docsPage = await readFile(
+      fileURLToPath(
+        new URL(
+          "../../../docs/src/content/docs/applications/n8n.mdx",
+          import.meta.url,
+        ),
+      ),
+      "utf8",
+    );
+
+    expect(syncScript).toContain("--apply");
+    expect(syncScript).toContain("installedPluginApps");
+    expect(syncScript).toContain("n8nAppData");
+    expect(syncScript).toContain("mutates: false");
+    expect(syncScript).toContain("redact");
+    expect(smokeScript).toContain("SMOKE_ENABLE_N8N_INTEGRATED_APP");
+    expect(smokeScript).toContain("installedPluginApps");
+    expect(smokeScript).toContain("n8nAppData");
+    expect(smokeScript).toContain("bridgeLinkedExecutionCount");
+    expect(smokeScript).toContain("redact");
+    expect(runbook).toContain("/apps/n8n/workflows");
+    expect(runbook).toContain("Settings -> Plugins -> n8n");
+    expect(runbook).toContain("sync-thinkwork-app.mjs");
+    expect(smokeReadme).toContain("n8n-integrated-app-smoke.mjs");
+    expect(smokeReadme).toContain("SMOKE_N8N_BRIDGE_THREAD_ID");
+    expect(docsPage).toContain("/apps/n8n/workflows");
+    expect(docsPage).toContain("Refresh catalog");
+
+    const syncOutput = JSON.parse(
+      execFileSync("node", [syncScriptPath], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        env: {
+          ...process.env,
+          N8N_THINKWORK_APP_SYNC_DRY_RUN: "1",
+        },
+      }),
+    );
+    expect(syncOutput.ok).toBe(true);
+    expect(syncOutput.mode).toBe("dry-run");
+    expect(syncOutput.dryRun.mutates).toBe(false);
+    expect(syncOutput.route).toBe("/apps/n8n/workflows");
+
+    const smokeOutput = JSON.parse(
+      execFileSync("node", [smokeScriptPath], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        env: {
+          ...process.env,
+          SMOKE_ENABLE_N8N_INTEGRATED_APP: "",
+          SMOKE_EVIDENCE_FILE: "",
+        },
+      }),
+    );
+    expect(smokeOutput.ok).toBe(true);
+    expect(smokeOutput.skippedLive).toBe(true);
+    expect(smokeOutput.dryRun.route).toBe("/apps/n8n/workflows");
+  });
+
+  it("filters and labels workflow and execution rows without exposing write controls", () => {
+    const workflows: N8nAppWorkflowRow[] = [
+      {
+        externalWorkflowId: "wf-ready",
+        name: "Lead Intake",
+        active: true,
+        triggerTypes: ["webhook"],
+        readinessState: "ready",
+        readinessReasons: {},
+        connectedWorkflowId: "tw-workflow",
+        connectedBindingId: "binding",
+        nativeWorkflowUrl: "https://n8n.example/workflow/wf-ready",
+        warnings: [],
+      },
+      {
+        externalWorkflowId: "wf-blocked",
+        name: "Draft Sync",
+        active: false,
+        triggerTypes: ["manual"],
+        readinessState: "blocked_not_ready",
+        readinessReasons: {},
+        warnings: ["missing bridge binding"],
+      },
+    ];
+    const executions: N8nAppExecutionRow[] = [
+      {
+        externalExecutionId: "exec-1",
+        externalWorkflowId: "wf-ready",
+        workflowName: "Lead Intake",
+        status: "success",
+        mode: "webhook",
+        durationMs: 1250,
+        nativeExecutionUrl: "https://n8n.example/execution/exec-1",
+        nativeWorkflowUrl: "https://n8n.example/workflow/wf-ready",
+        bridgeRuns: [
+          {
+            id: "run-1",
+            threadId: "thread-1",
+            status: "RESUMED",
+            resumeStatus: "RESUMED",
+            summary: "Thread resumed",
+            updatedAt: "2026-06-30T12:00:00.000Z",
+          },
+        ],
+        warnings: [],
+      },
+      {
+        externalExecutionId: "exec-2",
+        externalWorkflowId: "wf-blocked",
+        workflowName: "Draft Sync",
+        status: "failed",
+        mode: "manual",
+        durationMs: null,
+        failureMessage: "Webhook returned 500",
+        nativeExecutionUrl: "https://n8n.example/execution/exec-2",
+        nativeWorkflowUrl: "https://n8n.example/workflow/wf-blocked",
+        bridgeRuns: [],
+        warnings: [],
+      },
+    ];
+
+    expect(filterN8nWorkflows(workflows, "lead", "ready")).toEqual([
+      workflows[0],
+    ]);
+    expect(filterN8nWorkflows(workflows, "missing", "all")).toEqual([
+      workflows[1],
+    ]);
+    expect(connectionLabel(workflows[0])).toBe("linked");
+    expect(connectionLabel(workflows[1])).toBe("unlinked");
+    expect(readinessLabel("blocked_not_ready")).toBe("blocked");
+    expect(filterN8nExecutions(executions, "thread", "success")).toEqual([
+      executions[0],
+    ]);
+    expect(filterN8nExecutions(executions, "500", "failed")).toEqual([
+      executions[1],
+    ]);
+    expect(executionStatuses(executions)).toEqual(["failed", "success"]);
+    expect(formatDuration(1250)).toBe("1.3 s");
+    expect(formatDuration(119500)).toBe("1m 59s");
+    expect(bridgeThreadPath(executions[0].bridgeRuns[0])).toBe(
+      "/threads/thread-1",
+    );
+  });
+});

package/dist/plugins/n8n/test/manifest.test.ts

@@ -0,0 +1,278 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { defineFirstPartyPluginPackage } from "@thinkwork/plugin-catalog/plugin-package";
+import {
+  validatePluginManifest,
+  type PluginComponent,
+} from "@thinkwork/plugin-catalog/contracts";
+
+import {
+  N8N_AGENT_STEP_BRIDGE_CREDENTIAL_KIND,
+  N8N_AGENT_STEP_BRIDGE_CREDENTIAL_SECRET_JSON_KEY,
+  N8N_AGENT_STEP_BRIDGE_ENDPOINT_PATH,
+  N8N_MCP_ENDPOINT_PATH,
+  N8N_WORKFLOW_OPERATOR_MCP_TOOLING_REFERENCE_MD,
+  N8N_PLUGIN_LEGACY_VERSION,
+  N8N_PLUGIN_VERSION,
+  N8N_SERVICE_CREDENTIAL_KIND,
+  N8N_SERVICE_CREDENTIAL_SECRET_JSON_KEY,
+  N8N_WORKFLOW_OPERATOR_VALIDATION_AND_HANDOFF_REFERENCE_MD,
+  N8N_WORKFLOW_OPERATOR_SKILL_MD,
+  N8N_WORKFLOW_OPERATOR_SKILL_SLUG,
+  N8N_WORKFLOW_OPERATOR_WORKFLOW_AUTHORING_REFERENCE_MD,
+  n8nManifest,
+} from "../src/manifest";
+import { n8nPluginPackage } from "../src/index";
+
+describe("n8n plugin manifest", () => {
+  it("publishes a valid first-party package descriptor", () => {
+    const validatedPackage = defineFirstPartyPluginPackage(n8nPluginPackage);
+
+    expect(validatedPackage).toMatchObject({
+      packageKey: "n8n",
+      sourceRoot: "plugins/n8n",
+      manifest: n8nManifest,
+      compatibilityLinks: [],
+    });
+    expect("draftManifest" in n8nPluginPackage).toBe(false);
+    expect("publicationStatus" in n8nPluginPackage).toBe(false);
+    expect(validatedPackage.ownedSources.map((source) => source.kind)).toEqual([
+      "manifest",
+      "deployment",
+      "terraform",
+      "runtime",
+      "web",
+      "web",
+      "skills",
+      "smoke",
+      "tests",
+      "docs",
+    ]);
+  });
+
+  it("declares the final runtime, MCP, settings, and skill components", () => {
+    const manifest = validatePluginManifest(n8nManifest);
+    const version = manifest.versions[0]!;
+
+    expect(manifest).toMatchObject({
+      pluginKey: "n8n",
+      displayName: "n8n",
+      description: expect.stringContaining("workflow automation runtime"),
+    });
+    expect(manifest.versions.map((entry) => entry.version)).toEqual([
+      N8N_PLUGIN_LEGACY_VERSION,
+      N8N_PLUGIN_VERSION,
+    ]);
+    expect(version.version).toBe(N8N_PLUGIN_LEGACY_VERSION);
+    expect(version.requiredOauthScopes).toEqual([]);
+    expect(version.components.map((component) => component.type)).toEqual([
+      "infrastructure",
+      "mcp-server",
+      "ui-surface",
+      "skills",
+    ]);
+  });
+
+  it("maps infrastructure inputs onto the n8n managed-app adapter contract", () => {
+    const infra = component("infrastructure");
+
+    expect(infra).toMatchObject({
+      key: "runtime",
+      managedAppKey: "n8n",
+    });
+    expect(Object.keys(infra.terraformInputs)).toEqual([
+      "imageUri",
+      "databaseAdminSecretArn",
+      "databaseUrlSecretArn",
+      "encryptionKeySecretArn",
+      "operatorSecretArn",
+      "serviceCredentialSecretArn",
+      "agentStepBridgeCredentialSecretArn",
+      "storageBucketName",
+      "publicUrl",
+      "certificateArn",
+    ]);
+  });
+
+  it("uses tenant service credential auth for the native n8n MCP endpoint", () => {
+    const mcp = component("mcp-server");
+
+    expect(mcp).toMatchObject({
+      key: "workflow-management",
+      displayName: "n8n workflow management",
+      endpointFrom: {
+        managedApp: "n8n",
+        configKey: "publicUrl",
+        path: N8N_MCP_ENDPOINT_PATH,
+      },
+      auth: {
+        mode: "tenant-service-credential",
+        credentialKind: N8N_SERVICE_CREDENTIAL_KIND,
+        secretRefConfigKey: "serviceCredentialSecretArn",
+        headers: [
+          {
+            name: "Authorization",
+            secretJsonKey: N8N_SERVICE_CREDENTIAL_SECRET_JSON_KEY,
+            valuePrefix: "Bearer ",
+          },
+        ],
+      },
+    });
+    expect(mcp.toolNotes?.join("\n")).toContain("enable instance-level MCP");
+    expect(mcp.toolNotes?.join("\n")).toContain("separate inbound tenant");
+    expect(mcp.toolNotes?.join("\n")).toContain("production activation");
+    expect(N8N_AGENT_STEP_BRIDGE_ENDPOINT_PATH).toBe(
+      "/api/integrations/n8n/agent-steps",
+    );
+    expect(N8N_AGENT_STEP_BRIDGE_CREDENTIAL_KIND).toBe(
+      "n8n-agent-step-bridge-token",
+    );
+    expect(N8N_AGENT_STEP_BRIDGE_CREDENTIAL_SECRET_JSON_KEY).toBe(
+      "THINKWORK_N8N_AGENT_STEP_BRIDGE_TOKEN",
+    );
+  });
+
+  it("declares Plugin Detail custom package settings and operator instructions", async () => {
+    const ui = component("ui-surface");
+    const skills = component("skills");
+
+    expect(ui).toMatchObject({
+      key: "package-settings",
+      displayName: "n8n custom package settings",
+      intendedMount: "settings.plugins.detail",
+    });
+    expect(skills.skills).toHaveLength(1);
+    expect(skills.skills[0]).toMatchObject({
+      slug: N8N_WORKFLOW_OPERATOR_SKILL_SLUG,
+      skillMd: N8N_WORKFLOW_OPERATOR_SKILL_MD,
+    });
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_SLUG).toBe("n8n-workflow-operator");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_SLUG).toMatch(
+      /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,63}$/,
+    );
+    expect(skills.skills[0]?.supportingFiles?.map((file) => file.path)).toEqual(
+      [
+        "references/mcp-tooling.md",
+        "references/workflow-authoring.md",
+        "references/validation-and-handoff.md",
+      ],
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "name: n8n-workflow-operator",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain("license: Apache-2.0");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "skill-format: agentskills",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain("MCP tooling");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "references/mcp-tooling.md",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "references/workflow-authoring.md",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "references/validation-and-handoff.md",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain("HTTP Request");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain("Wait nodes");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain("$execution.resumeUrl");
+    expect(N8N_WORKFLOW_OPERATOR_SKILL_MD).toContain(
+      "custom ThinkWork n8n node",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_MCP_TOOLING_REFERENCE_MD).toContain(
+      "nodes-base.httpRequest",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_MCP_TOOLING_REFERENCE_MD).toContain(
+      "n8n-nodes-base.httpRequest",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_MCP_TOOLING_REFERENCE_MD).toContain(
+      "Shortened Tool Names",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_WORKFLOW_AUTHORING_REFERENCE_MD).toContain(
+      "Manual trigger",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_WORKFLOW_AUTHORING_REFERENCE_MD).toContain(
+      "$json.body",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_VALIDATION_AND_HANDOFF_REFERENCE_MD).toContain(
+      "Validation passing is necessary, not sufficient",
+    );
+    expect(N8N_WORKFLOW_OPERATOR_VALIDATION_AND_HANDOFF_REFERENCE_MD).toContain(
+      "Handoff Checklist",
+    );
+
+    const skillRoot = new URL(
+      "../src/skills/n8n-workflow-operator/",
+      import.meta.url,
+    );
+
+    const skillFile = await readFile(
+      fileURLToPath(new URL("SKILL.md", skillRoot)),
+      "utf8",
+    );
+    expect(skillFile).toBe(N8N_WORKFLOW_OPERATOR_SKILL_MD);
+    await expect(
+      readFile(fileURLToPath(new URL("references/mcp-tooling.md", skillRoot)), {
+        encoding: "utf8",
+      }),
+    ).resolves.toBe(N8N_WORKFLOW_OPERATOR_MCP_TOOLING_REFERENCE_MD);
+    await expect(
+      readFile(
+        fileURLToPath(new URL("references/workflow-authoring.md", skillRoot)),
+        { encoding: "utf8" },
+      ),
+    ).resolves.toBe(N8N_WORKFLOW_OPERATOR_WORKFLOW_AUTHORING_REFERENCE_MD);
+    await expect(
+      readFile(
+        fileURLToPath(
+          new URL("references/validation-and-handoff.md", skillRoot),
+        ),
+        { encoding: "utf8" },
+      ),
+    ).resolves.toBe(N8N_WORKFLOW_OPERATOR_VALIDATION_AND_HANDOFF_REFERENCE_MD);
+  });
+
+  it("keeps LastMile runtime source out of the n8n package", async () => {
+    const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+    const packagePaths = await listPackagePaths(packageRoot);
+
+    expect(
+      packagePaths.filter((path) =>
+        /lastmile|custom-node|credential/i.test(path),
+      ),
+    ).toEqual([]);
+  });
+});
+
+function component<TType extends PluginComponent["type"]>(
+  type: TType,
+): Extract<PluginComponent, { type: TType }> {
+  const found = n8nManifest.versions[0]!.components.find(
+    (entry) => entry.type === type,
+  );
+  if (!found) throw new Error(`Missing n8n manifest component ${type}`);
+  return found as Extract<PluginComponent, { type: TType }>;
+}
+
+async function listPackagePaths(root: string): Promise<string[]> {
+  const paths: string[] = [];
+  async function walk(dir: string) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const absolutePath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolutePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        paths.push(absolutePath.slice(root.length + 1).replaceAll("\\", "/"));
+      }
+    }
+  }
+  await walk(root);
+  return paths.sort();
+}

package/dist/plugins/n8n/test/package-config.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { normalizeN8nPackageConfig } from "../src/package-config";
+
+describe("n8n package config", () => {
+  it("normalizes exact public npm specs into a deterministic digest", () => {
+    const first = normalizeN8nPackageConfig({
+      customPackageSpecs: [
+        "zod@3.25.76",
+        "lodash@4.17.21",
+        "@aws-sdk/client-s3@3.844.0",
+        "lodash@4.17.21",
+      ],
+    });
+    const second = normalizeN8nPackageConfig([
+      "lodash@4.17.21",
+      "@aws-sdk/client-s3@3.844.0",
+      "zod@3.25.76",
+    ]);
+
+    expect(first.packageSpecs).toEqual([
+      "@aws-sdk/client-s3@3.844.0",
+      "lodash@4.17.21",
+      "zod@3.25.76",
+    ]);
+    expect(first.packageNames).toEqual(["@aws-sdk/client-s3", "lodash", "zod"]);
+    expect(first.allowExternal).toBe("@aws-sdk/client-s3,lodash,zod");
+    expect(first.digest).toMatch(/^[a-f0-9]{64}$/);
+    expect(first.digest).toBe(second.digest);
+  });
+
+  it("rejects unpinned ranges, tags, URLs, paths, and private registry aliases", () => {
+    const invalidSpecs = [
+      "lodash",
+      "lodash@^4.17.21",
+      "lodash@latest",
+      "lodash@*",
+      "git+https://github.com/lodash/lodash.git",
+      "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+      "file:../lodash",
+      "workspace:lodash",
+      "npm:lodash@4.17.21",
+      "../local-package",
+    ];
+
+    for (const spec of invalidSpecs) {
+      expect(() => normalizeN8nPackageConfig([spec]), spec).toThrow(
+        /exact public npm|exact semver|public npm registry|URL|path|workspace/,
+      );
+    }
+  });
+
+  it("rejects conflicting package versions", () => {
+    expect(() =>
+      normalizeN8nPackageConfig(["date-fns@4.1.0", "date-fns@4.0.0"]),
+    ).toThrow(/multiple versions/);
+  });
+});

package/dist/plugins/n8n/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["./**/*.ts"]
+}