thinkwork-cli 0.12.11 → 0.12.15

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

@@ -0,0 +1,463 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { managedAppRegistry } from "@thinkwork/deployment-runner/apps/registry";
+
+import {
+  PluginManifestError,
+  validatePluginManifest,
+  type InfrastructureComponent,
+  type McpServerComponent,
+  type PluginManifest,
+  type UiSurfaceComponent,
+} from "@thinkwork/plugin-catalog/contracts";
+import { defineFirstPartyPluginPackage } from "@thinkwork/plugin-catalog/plugin-package";
+
+import { twentyPluginPackage } from "../src";
+import { twentyManifest } from "../src/manifest";
+
+const validatedTwentyManifest = validatePluginManifest(twentyManifest);
+const testDir = dirname(fileURLToPath(import.meta.url));
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function manifest(mutate?: (manifest: PluginManifest) => void): PluginManifest {
+  const copy = validatePluginManifest(clone(twentyManifest));
+  mutate?.(copy);
+  return copy;
+}
+
+function mcpComponent(m: PluginManifest): McpServerComponent {
+  const component = m.versions[0].components.find(
+    (candidate) => candidate.type === "mcp-server",
+  );
+  if (component?.type !== "mcp-server") {
+    throw new Error("twenty manifest is missing its mcp-server component");
+  }
+  return component;
+}
+
+function latestVersion(m: PluginManifest) {
+  return [...m.versions].sort((a, b) =>
+    b.version.localeCompare(a.version, undefined, { numeric: true }),
+  )[0]!;
+}
+
+function latestMcpComponent(m: PluginManifest): McpServerComponent {
+  const component = latestVersion(m).components.find(
+    (candidate) => candidate.type === "mcp-server",
+  );
+  if (component?.type !== "mcp-server") {
+    throw new Error(
+      "latest twenty manifest is missing its mcp-server component",
+    );
+  }
+  return component;
+}
+
+function latestUiSurfaceComponent(m: PluginManifest): UiSurfaceComponent {
+  const component = latestVersion(m).components.find(
+    (candidate) => candidate.type === "ui-surface",
+  );
+  if (component?.type !== "ui-surface") {
+    throw new Error("latest twenty manifest is missing its ui-surface");
+  }
+  return component;
+}
+
+function infrastructureComponent(): InfrastructureComponent {
+  const component = latestVersion(validatedTwentyManifest).components.find(
+    (candidate) => candidate.type === "infrastructure",
+  );
+  if (component?.type !== "infrastructure") {
+    throw new Error("twenty manifest is missing its infrastructure component");
+  }
+  return component;
+}
+
+function adapterRequiredInputs(operation: "ENABLE" | "UPGRADE"): string[] {
+  const adapter = managedAppRegistry.find(
+    (candidate) => candidate.appKey === "twenty",
+  );
+  if (!adapter) {
+    throw new Error("Twenty managed-app adapter is not registered");
+  }
+  return adapter
+    .requiredInputs(operation)
+    .map((input) => input.key)
+    .sort();
+}
+
+function readTwentyApp(path: string): string {
+  return readFileSync(join(testDir, "..", "twenty-app", path), "utf8");
+}
+
+function readRepo(path: string): string {
+  return readFileSync(join(testDir, "..", "..", "..", path), "utf8");
+}
+
+describe("twenty plugin manifest", () => {
+  it("validates: one endpointFrom mcp-server + one infrastructure component", () => {
+    const validated = validatePluginManifest(twentyManifest);
+    expect(validated.pluginKey).toBe("twenty");
+    expect(validated.versions[0].version).toBe("0.1.0");
+    expect(validated.versions.map((version) => version.version)).toEqual([
+      "0.1.0",
+      "0.2.0",
+      "0.3.0",
+    ]);
+
+    const components = latestVersion(validated).components;
+    expect(components.map((component) => component.type).sort()).toEqual([
+      "infrastructure",
+      "mcp-server",
+      "ui-surface",
+    ]);
+
+    const mcp = latestMcpComponent(validated);
+    expect(mcp.endpointUrl).toBeUndefined();
+    expect(mcp.endpointFrom).toEqual({
+      managedApp: "twenty",
+      configKey: "publicUrl",
+      path: "/mcp",
+    });
+    expect(mcp.auth).toEqual({ mode: "oauth-per-instance" });
+  });
+
+  it("preserves older MCP contracts and keeps record-link hints in launchable versions", () => {
+    const validated = validatePluginManifest(twentyManifest);
+    const legacyMcp = mcpComponent(validated);
+    const recordLinkVersion = validated.versions.find(
+      (version) => version.version === "0.2.0",
+    );
+    const recordLinkMcp = recordLinkVersion?.components.find(
+      (component) => component.type === "mcp-server",
+    );
+    const latestMcp = latestMcpComponent(validated);
+
+    expect(validated.versions[0].version).toBe("0.1.0");
+    expect(legacyMcp.recordLinkHints).toBeUndefined();
+    expect(recordLinkMcp?.type).toBe("mcp-server");
+    expect(
+      recordLinkMcp?.type === "mcp-server"
+        ? recordLinkMcp.recordLinkHints
+        : undefined,
+    ).toEqual({
+      schemaVersion: 1,
+      source: "plugin-manifest",
+      routes: [
+        {
+          objectType: "opportunity",
+          routeTemplate: "/object/opportunity/{id}",
+          idFields: ["id", "opportunityId", "record.id", "opportunity.id"],
+          labelFields: [
+            "name",
+            "opportunityName",
+            "record.name",
+            "opportunity.name",
+          ],
+        },
+      ],
+    });
+    expect(latestVersion(validated).version).toBe("0.3.0");
+    expect(latestMcp.recordLinkHints).toEqual({
+      schemaVersion: 1,
+      source: "plugin-manifest",
+      routes: [
+        {
+          objectType: "opportunity",
+          routeTemplate: "/object/opportunity/{id}",
+          idFields: ["id", "opportunityId", "record.id", "opportunity.id"],
+          labelFields: [
+            "name",
+            "opportunityName",
+            "record.name",
+            "opportunity.name",
+          ],
+        },
+      ],
+    });
+  });
+
+  it("publishes a launchable Client Engagement app surface in the latest version", () => {
+    const surface = latestUiSurfaceComponent(validatedTwentyManifest);
+
+    expect(surface).toEqual({
+      type: "ui-surface",
+      key: "client-engagement",
+      displayName: "Client Engagement",
+      intendedMount: "apps.main",
+      launch: {
+        schemaVersion: 1,
+        type: "app",
+        appKey: "twenty-client-engagement",
+        routeSegment: "client-engagement",
+        mount: "main-shell",
+        runtime: "trusted-bundled-react",
+        description:
+          "Account and opportunity engagement workspace for Twenty CRM records.",
+        icon: "layout-dashboard",
+        entitlementProductKey: "twenty-client-engagement",
+      },
+    });
+  });
+
+  it("owns a native Twenty app package for the ThinkWork Webhook workflow action", () => {
+    const defined = defineFirstPartyPluginPackage(twentyPluginPackage);
+
+    expect(defined.ownedSources).toContainEqual({
+      kind: "runtime",
+      path: "plugins/twenty/twenty-app",
+      description:
+        "Native Twenty app package that exposes the ThinkWork Webhook workflow action.",
+    });
+
+    const appYarnLock = readTwentyApp("yarn.lock");
+    const appNvmrc = readTwentyApp(".nvmrc");
+    const appPackageJson = readTwentyApp("package.json");
+    const appReadme = readTwentyApp("README.md");
+    const applicationConfig = readTwentyApp("src/application-config.ts");
+    const settingsComponent = readTwentyApp(
+      "src/front-components/thinkwork-settings.front-component.tsx",
+    );
+    const workflowAction = readTwentyApp(
+      "src/logic-functions/thinkwork-webhook.logic-function.ts",
+    );
+
+    expect(appYarnLock).toContain("twenty-sdk@npm:2.9.0");
+    expect(appYarnLock).toContain("twenty-client-sdk@npm:2.9.0");
+    expect(appNvmrc.trim()).toBe("24");
+    expect(appPackageJson).toContain('"twenty": ">=2.9.0 <3.0.0"');
+    expect(appReadme).toContain(
+      "docs/runbooks/twenty-thinkwork-native-app-install.md",
+    );
+    expect(applicationConfig).toContain("defineApplication");
+    expect(applicationConfig).toContain("displayName: APP_DISPLAY_NAME");
+    expect(applicationConfig).toContain(
+      "settingsCustomTabFrontComponentUniversalIdentifier",
+    );
+    expect(applicationConfig).toContain(
+      "THINKWORK_SETTINGS_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER",
+    );
+    expect(applicationConfig).toContain("THINKWORK_WEBHOOK_URL");
+    expect(applicationConfig).toContain("isSecret: true");
+    expect(applicationConfig).toContain("THINKWORK_TRIGGER_STAGE");
+    expect(applicationConfig).toContain('value: "Customer"');
+    expect(applicationConfig).toContain("TWENTY_WORKSPACE_ID");
+    expect(applicationConfig).toContain("014f32a0-5868-402a-8152-225e54c4cf29");
+    expect(settingsComponent).toContain("defineFrontComponent");
+    expect(settingsComponent).toContain(
+      "THINKWORK_SETTINGS_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER",
+    );
+    expect(settingsComponent).toContain("updateOneApplicationVariable");
+    expect(settingsComponent).toContain("THINKWORK_WEBHOOK_URL");
+    expect(settingsComponent).toContain("THINKWORK_TRIGGER_STAGE");
+    expect(settingsComponent).toContain("TWENTY_WORKSPACE_ID");
+    expect(settingsComponent).toContain("Customer");
+    expect(workflowAction).toContain("defineLogicFunction");
+    expect(workflowAction).not.toContain("databaseEventTriggerSettings");
+    expect(workflowAction).toContain("workflowActionTriggerSettings");
+    expect(workflowAction).toContain('label: "ThinkWork Webhook"');
+    expect(workflowAction).toContain("process.env.THINKWORK_WEBHOOK_URL");
+    expect(workflowAction).toContain("process.env.THINKWORK_TRIGGER_STAGE");
+    expect(workflowAction).toContain("process.env.TWENTY_WORKSPACE_ID");
+    expect(workflowAction).toContain("/object/opportunity/");
+    expect(workflowAction).toContain("objects\\/opportunities");
+    expect(workflowAction).toContain('status: "skipped_stage"');
+    expect(workflowAction).toContain("triggerStage: configuredStage");
+    expect(workflowAction).toContain('source: "twenty-app"');
+    expect(workflowAction).not.toContain("opportunity.won");
+  });
+
+  it("documents native app release packaging and guarded sync paths", () => {
+    const releaseWorkflow = readRepo(".github/workflows/release.yml");
+    const deployWorkflow = readRepo(".github/workflows/deploy.yml");
+    const operationsWorkflow = readRepo(
+      ".github/workflows/twenty-thinkwork-app.yml",
+    );
+    const manifestBuilder = readRepo(
+      "scripts/release/build-release-manifest.ts",
+    );
+    const runner = readRepo(
+      "terraform/modules/app/deployment-control-plane/runner.py",
+    );
+    const syncScript = readRepo(
+      "plugins/twenty/scripts/sync-thinkwork-app.mjs",
+    );
+    const wireScript = readRepo(
+      "plugins/twenty/scripts/wire-thinkwork-workflow.mjs",
+    );
+
+    expect(releaseWorkflow).toContain("Stage Twenty ThinkWork app package");
+    expect(releaseWorkflow).toContain("twenty-thinkwork-app.tar.gz");
+    expect(releaseWorkflow).toContain("name=twenty-thinkwork-app,type=seed");
+    expect(manifestBuilder).toContain(
+      'requiredArtifacts: ["twenty-thinkwork-app"]',
+    );
+    expect(runner).toContain("stage_managed_app_release_artifacts");
+    expect(runner).toContain("sync_twenty_thinkwork_app");
+    expect(runner).toContain("twentyAppSyncApiKey");
+    expect(runner).toContain("managedAppPostInstall");
+    expect(deployWorkflow).toContain("sync_twenty_thinkwork_app");
+    expect(deployWorkflow).toContain("TWENTY_DEPLOY_API_KEY");
+    expect(deployWorkflow).toContain("TWENTY_APP_SYNC_API_KEY");
+    expect(deployWorkflow).toContain("TWENTY_WORKSPACE_ID");
+    expect(deployWorkflow).toContain("sync-thinkwork-app.mjs");
+    expect(deployWorkflow).toContain("wire-thinkwork-workflow.mjs");
+    expect(operationsWorkflow).toContain("Twenty ThinkWork App Operations");
+    expect(operationsWorkflow).toContain("validate-package");
+    expect(operationsWorkflow).toContain("APPLY TWENTY THINKWORK APP");
+    expect(operationsWorkflow).toContain(
+      "YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install",
+    );
+    expect(operationsWorkflow).toContain("TWENTY_DEPLOY_API_KEY");
+    expect(operationsWorkflow).toContain("TWENTY_WORKSPACE_ID");
+    expect(operationsWorkflow).toContain("sync-thinkwork-app.mjs");
+    expect(operationsWorkflow).toContain("wire-thinkwork-workflow.mjs");
+    expect(operationsWorkflow).toContain("twenty_allow_active_update");
+    expect(operationsWorkflow).toContain("WIRE_ALLOW_ACTIVE_UPDATE");
+    expect(operationsWorkflow).not.toContain("terraform-apply");
+    expect(syncScript).toContain("app:publish");
+    expect(syncScript).toContain("--private");
+    expect(syncScript).toContain("app:install");
+    expect(syncScript).toContain("remote:status");
+    expect(syncScript).toContain("--dry-run");
+    expect(syncScript).not.toContain("HTTP_REQUEST");
+    expect(wireScript).toContain('type: "LOGIC_FUNCTION"');
+    expect(wireScript).toContain("UpdateWorkflowVersionStep");
+    expect(wireScript).toContain("findManyLogicFunctions");
+    expect(wireScript).toContain('path: "/metadata"');
+    expect(wireScript).toContain("findThinkWorkLogicFunction(metadataClient)");
+    expect(wireScript).toContain("findWorkflowVersionsForWorkflow");
+    expect(wireScript).toContain("--allow-active-update");
+    expect(wireScript).toContain("--workspace-id");
+    expect(wireScript).toContain("/object/${objectName}/");
+    expect(wireScript).toContain('objectName: "opportunity"');
+    expect(wireScript).not.toContain("/objects/opportunities/");
+    expect(wireScript).toContain("{{trigger.properties.after.id}}");
+    expect(wireScript).toContain("{{trigger.properties.after.name}}");
+    expect(wireScript).toContain("{{trigger.properties.after.companyId}}");
+    expect(wireScript).toContain("{{trigger.properties.after.updatedAt}}");
+    expect(wireScript).toContain(
+      "{{trigger.properties.after.amount.amountMicros}}",
+    );
+    expect(wireScript).not.toContain("{{trigger.object.");
+    expect(wireScript).not.toContain("AWS_LAMBDA");
+  });
+
+  it("enables Twenty local logic functions for the first-party workflow action", () => {
+    const terraformModule = readRepo("plugins/twenty/terraform/twenty/main.tf");
+    const terraformReadme = readRepo(
+      "plugins/twenty/terraform/twenty/README.md",
+    );
+
+    expect(terraformModule).toContain(
+      '{ name = "LOGIC_FUNCTION_TYPE", value = "LOCAL" }',
+    );
+    expect(terraformModule).toContain("server_environment = concat");
+    expect(terraformModule).toContain("worker_environment = concat");
+    expect(terraformReadme).toContain("LOGIC_FUNCTION_TYPE=LOCAL");
+    expect(terraformReadme).toContain("ThinkWork Webhook");
+  });
+
+  it("declares the infrastructure component against the twenty adapter key", () => {
+    const infra = infrastructureComponent();
+    expect(infra.managedAppKey).toBe("twenty");
+    expect(Object.keys(infra.terraformInputs).sort()).toEqual([
+      "certificateArn",
+      "dbUrlSecretArn",
+      "encryptionKeySecretArn",
+      "imageUri",
+      "publicUrl",
+    ]);
+    for (const spec of Object.values(infra.terraformInputs)) {
+      expect(spec.description.length).toBeGreaterThan(0);
+      expect(spec.type).toBe("string");
+    }
+  });
+
+  it("keeps infrastructure inputs aligned with the managed-app adapter", () => {
+    const inputs = Object.keys(
+      infrastructureComponent().terraformInputs,
+    ).sort();
+    expect(inputs).toEqual(adapterRequiredInputs("ENABLE"));
+    expect(inputs).toEqual(adapterRequiredInputs("UPGRADE"));
+    expect(inputs).toContain(
+      mcpComponent(validatedTwentyManifest).endpointFrom?.configKey,
+    );
+  });
+
+  it("rejects a component declaring both endpointUrl and endpointFrom", () => {
+    const bad = manifest();
+    mcpComponent(bad).endpointUrl = "https://crm.example.com/mcp";
+    expect(() => validatePluginManifest(bad)).toThrow(
+      /exactly one of endpointUrl \/ endpointFrom/,
+    );
+  });
+
+  it("rejects a component declaring neither endpointUrl nor endpointFrom", () => {
+    const bad = manifest();
+    delete mcpComponent(bad).endpointFrom;
+    expect(() => validatePluginManifest(bad)).toThrow(
+      /exactly one of endpointUrl \/ endpointFrom/,
+    );
+  });
+
+  it("rejects endpointFrom missing its configKey", () => {
+    const bad = manifest();
+    delete (mcpComponent(bad).endpointFrom as { configKey?: string }).configKey;
+    expect(() => validatePluginManifest(bad)).toThrow(
+      /endpointFrom\.configKey/,
+    );
+  });
+
+  it("rejects an endpointFrom path that is not absolute or carries a query", () => {
+    const noSlash = manifest();
+    mcpComponent(noSlash).endpointFrom!.path = "mcp";
+    expect(() => validatePluginManifest(noSlash)).toThrow(
+      /path must start with "\/"/,
+    );
+
+    const query = manifest();
+    mcpComponent(query).endpointFrom!.path = "/mcp?x=1";
+    expect(() => validatePluginManifest(query)).toThrow(PluginManifestError);
+  });
+
+  it("rejects oauth-per-instance auth on a static-endpoint server", () => {
+    const bad = manifest();
+    const mcp = mcpComponent(bad);
+    delete mcp.endpointFrom;
+    mcp.endpointUrl = "https://crm.example.com/mcp";
+    expect(() => validatePluginManifest(bad)).toThrow(
+      /"oauth-per-instance" requires endpointFrom/,
+    );
+  });
+
+  it("still requires non-empty scopes for STATIC oauth servers", () => {
+    // The per-instance exemption must not relax the static-server rule.
+    const bad = manifest();
+    const mcp = mcpComponent(bad);
+    delete mcp.endpointFrom;
+    mcp.endpointUrl = "https://crm.example.com/mcp";
+    mcp.auth = {
+      mode: "oauth",
+      authDomain: "https://auth.example.com",
+      resourceIndicator: "https://crm.example.com/mcp",
+    };
+    expect(() => validatePluginManifest(bad)).toThrow(
+      /non-empty requiredOauthScopes/,
+    );
+  });
+
+  it("allows empty requiredOauthScopes for a per-instance-only manifest", () => {
+    expect(
+      validatedTwentyManifest.versions.map(
+        (version) => version.requiredOauthScopes,
+      ),
+    ).toEqual([[], [], []]);
+    expect(() => validatePluginManifest(twentyManifest)).not.toThrow();
+  });
+});

package/dist/plugins/twenty/tsconfig.json

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

package/dist/plugins/twenty/twenty-app/.nvmrc

@@ -0,0 +1 @@
+24

package/dist/plugins/twenty/twenty-app/README.md

@@ -0,0 +1,148 @@
+# ThinkWork Twenty App
+
+Native Twenty app source for the THNK-33 workflow path:
+
+```text
+Twenty workflow -> ThinkWork app -> ThinkWork Webhook
+```
+
+The app exposes:
+
+- one settings front component, `thinkwork-settings`, rendered by the native
+  Twenty app Settings tab;
+- one logic function, `ThinkWork Webhook`, registered as a workflow action for
+  explicit workflow-builder use.
+
+The settings component writes `THINKWORK_WEBHOOK_URL`,
+`THINKWORK_TRIGGER_STAGE`, and `TWENTY_WORKSPACE_ID` as native Twenty
+application variables. The workflow action reads those variables, compares the
+incoming Twenty Opportunity stage with the configured app stage, and only posts
+to the configured ThinkWork generic webhook URL when they match.
+
+## Configuration
+
+After installing the app, open Twenty:
+
+```text
+Settings -> Applications -> Installed -> ThinkWork -> Settings
+```
+
+Set the app variables in the ThinkWork settings surface:
+
+| Variable                  | Required | Default                 | Description                                                                                                                            |
+| ------------------------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `THINKWORK_WEBHOOK_URL`   | yes      | none                    | Full ThinkWork generic webhook URL copied from ThinkWork Settings > Webhooks, for example `https://app.thinkwork.ai/webhooks/<token>`. |
+| `THINKWORK_TRIGGER_STAGE` | yes      | `Customer`              | Twenty Opportunity stage label that should trigger the ThinkWork webhook.                                                              |
+| `TWENTY_WORKSPACE_ID`     | no       | production workspace id | Twenty workspace id appended to canonical CRM record links.                                                                            |
+
+The webhook URL contains the ThinkWork webhook token, so the settings component
+does not display the saved secret value after save; paste a new URL to rotate
+it. The trigger stage defaults to `Customer` and is intentionally editable in
+the app settings so the mapping stays in Twenty's ThinkWork app configuration.
+
+## Workflow Action
+
+The logic function is available in the Twenty workflow builder as:
+
+```text
+ThinkWork -> ThinkWork Webhook
+```
+
+Recommended action input mapping:
+
+| Input             | Value                                                   |
+| ----------------- | ------------------------------------------------------- |
+| `event`           | optional; defaults to `opportunity.stage.customer`      |
+| `opportunityId`   | Current Opportunity record id                           |
+| `opportunityName` | Current Opportunity name                                |
+| `companyName`     | Current Opportunity company/account name when available |
+| `stage`           | Current Opportunity stage                               |
+| `opportunityUrl`  | Current Opportunity URL when available                  |
+| `workflowKey`     | `customer_onboarding`                                   |
+| `workflowRunId`   | Current workflow run id when available                  |
+| `occurredAt`      | Workflow run timestamp or current timestamp             |
+| `idempotencyKey`  | Stable key such as `stage-customer:<opportunity-id>`    |
+
+The logic function sends those fields to ThinkWork with
+`source: "twenty-app"` and `triggerStage: "<configured stage>"` when the
+incoming stage matches `THINKWORK_TRIGGER_STAGE`. If the stage does not match,
+the action returns `status: "skipped_stage"` and does not call ThinkWork.
+The action normalizes legacy Opportunity links like
+`/objects/opportunities/<id>` into Twenty's canonical
+`/object/opportunity/<id>#<workspace-id>` route before sending the payload.
+
+ThinkWork should record the resulting generic webhook delivery with
+`source=twenty-app`, `stage=Customer`, and `triggerStage=Customer`, proving that
+the path goes through the installed Twenty app settings.
+
+## Install / Deploy
+
+Do not run these commands against production from an implementation PR. They
+mutate the target Twenty instance.
+
+```bash
+cd plugins/twenty/twenty-app
+corepack enable
+yarn install
+yarn twenty remote:add --url https://crm.thinkwork.ai --api-key "$TWENTY_DEPLOY_API_KEY" --as thinkwork-crm
+yarn twenty dev --once --dry-run
+yarn twenty app:publish --private --remote thinkwork-crm
+yarn twenty app:install --remote thinkwork-crm
+```
+
+Or use the guarded operations workflow:
+
+```bash
+node plugins/twenty/scripts/sync-thinkwork-app.mjs --apply
+```
+
+For the full operator sequence, including deploy-key setup, dry-run, apply,
+settings, workflow wiring, and verification evidence, see
+`docs/runbooks/twenty-thinkwork-native-app-install.md`.
+
+Dry-run mode uses Twenty's non-mutating dev sync preview. Apply mode follows
+Twenty's private app lifecycle: deploy the app tarball with
+`app:publish --private`, then install it into the target workspace with
+`app:install`.
+
+After install, the Twenty Applications screen should show a native installed
+app named `ThinkWork`, the app Settings tab should render a
+`ThinkWork Webhook` configuration form for the webhook URL and trigger stage,
+and the workflow builder should offer a workflow action named
+`ThinkWork Webhook`.
+
+## Workflow Wiring
+
+The Opportunity workflow must call the app action rather than Twenty's built-in
+HTTP request action:
+
+```text
+Twenty Opportunity stage == Customer
+  -> ThinkWork -> ThinkWork Webhook
+  -> THINKWORK_WEBHOOK_URL from ThinkWork app settings
+```
+
+Use the guarded wiring script in dry-run mode first:
+
+```bash
+node plugins/twenty/scripts/wire-thinkwork-workflow.mjs \
+  --workflow-version-id <draft-workflow-version-id> \
+  --dry-run
+```
+
+When the dry-run report identifies the intended workflow and step, an operator
+can apply it to a draft workflow version:
+
+```bash
+node plugins/twenty/scripts/wire-thinkwork-workflow.mjs \
+  --workflow-version-id <draft-workflow-version-id> \
+  --step-id <http-request-step-id> \
+  --workspace-id <twenty-workspace-id> \
+  --apply
+```
+
+The Deploy workflow exposes the same guarded operation via
+`wire_twenty_thinkwork_workflow`. The script refuses to mutate an active
+workflow version unless an operator explicitly creates or targets a draft.
+Set the repository variable `TWENTY_WORKSPACE_ID` so generated Opportunity
+links use Twenty's canonical `/object/opportunity/<id>#<workspace-id>` route.

package/dist/plugins/twenty/twenty-app/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@thinkwork/twenty-app",
+  "version": "0.1.4",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": "^24.5.0",
+    "twenty": ">=2.9.0 <3.0.0",
+    "npm": "please-use-yarn",
+    "yarn": ">=4.0.2"
+  },
+  "packageManager": "yarn@4.13.0",
+  "scripts": {
+    "twenty": "twenty",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "twenty-client-sdk": "2.9.0",
+    "twenty-sdk": "2.9.0",
+    "typescript": "^5.9.3"
+  }
+}