thinkwork-cli 0.12.12 → 0.12.16

package/dist/plugins/sendgrid/README.md

@@ -0,0 +1,30 @@
+# SendGrid Plugin
+
+The SendGrid plugin is the package-owned source boundary for SendGrid-backed
+tenant invitation email. It declares SendGrid as a standalone email provider so
+operators can install and inspect it from Settings -> Plugins instead of finding
+SendGrid hidden inside the Resend channel package.
+
+Shared platform code owns credential storage, authenticated-domain discovery,
+readiness checks, provider selection, and invitation delivery. This package owns
+the catalog identity and provider capability contract.
+
+## Owned Source
+
+- `src/manifest.ts` declares the catalog manifest and email-channel capability.
+- `src/provider-contract.ts` holds SendGrid provider metadata and the shared
+  settings surface identity.
+- `test/manifest.test.ts` validates provider scope, settings surface, and
+  package descriptor boundaries.
+
+## Verification Notes
+
+Package-local verification:
+
+```bash
+pnpm --filter @thinkwork/plugin-sendgrid test
+pnpm --filter @thinkwork/plugin-sendgrid typecheck
+pnpm --filter @thinkwork/plugin-catalog test
+pnpm --filter @thinkwork/plugin-catalog typecheck
+node scripts/verify-plugin-source-boundary.mjs
+```

package/dist/plugins/sendgrid/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@thinkwork/plugin-sendgrid",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./provider-contract": "./src/provider-contract.ts"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@thinkwork/plugin-catalog": "workspace:*",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/dist/plugins/sendgrid/src/index.ts

@@ -0,0 +1,36 @@
+import { sendgridManifest } from "./manifest";
+
+export const sendgridPluginPackage = {
+  packageKey: "sendgrid",
+  sourceRoot: "plugins/sendgrid",
+  manifest: sendgridManifest,
+  ownedSources: [
+    {
+      kind: "manifest",
+      path: "plugins/sendgrid/src/manifest.ts",
+      description:
+        "SendGrid Email catalog manifest and provider capability contract.",
+    },
+    {
+      kind: "api",
+      path: "plugins/sendgrid/src/provider-contract.ts",
+      description:
+        "SendGrid Email provider keys and package-local channel contract metadata.",
+    },
+    {
+      kind: "tests",
+      path: "plugins/sendgrid/test",
+      description:
+        "SendGrid Email package-local manifest and provider scope tests.",
+    },
+    {
+      kind: "docs",
+      path: "plugins/sendgrid/README.md",
+      description: "SendGrid Email package ownership and verification notes.",
+    },
+  ],
+  compatibilityLinks: [],
+} as const;
+
+export { sendgridManifest };
+export * from "./provider-contract";

package/dist/plugins/sendgrid/src/manifest.ts

@@ -0,0 +1,37 @@
+import type { PluginManifest } from "@thinkwork/plugin-catalog/contracts";
+
+import {
+  SENDGRID_EMAIL_CHANNEL_CAPABILITY_KEY,
+  SENDGRID_SETTINGS_SURFACE,
+  sendGridEmailChannelProviders,
+} from "./provider-contract";
+
+export const sendgridManifest = {
+  pluginKey: "sendgrid",
+  displayName: "SendGrid Email",
+  description:
+    "SendGrid email provider for tenant member invitations with authenticated-domain readiness.",
+  versions: [
+    {
+      version: "0.1.0",
+      requiredOauthScopes: [],
+      capabilities: [
+        {
+          type: "email-channel",
+          key: SENDGRID_EMAIL_CHANNEL_CAPABILITY_KEY,
+          displayName: "SendGrid invitation email",
+          providers: sendGridEmailChannelProviders,
+          settingsSurface: SENDGRID_SETTINGS_SURFACE,
+        },
+      ],
+      components: [
+        {
+          type: "ui-surface",
+          key: "settings",
+          displayName: "SendGrid Email settings",
+          intendedMount: SENDGRID_SETTINGS_SURFACE,
+        },
+      ],
+    },
+  ],
+} satisfies PluginManifest;

package/dist/plugins/sendgrid/src/provider-contract.ts

@@ -0,0 +1,14 @@
+import type { EmailChannelProviderOption } from "@thinkwork/plugin-catalog/contracts";
+
+export const SENDGRID_EMAIL_CHANNEL_CAPABILITY_KEY =
+  "sendgrid-email-provider" as const;
+export const SENDGRID_SETTINGS_SURFACE =
+  "settings.plugins.email-channel" as const;
+
+export const sendGridEmailChannelProviders = [
+  {
+    key: "sendgrid",
+    displayName: "SendGrid",
+    recommended: true,
+  },
+] satisfies EmailChannelProviderOption[];

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  validatePluginManifest,
+  type EmailChannelCapability,
+  type PluginManifest,
+} from "@thinkwork/plugin-catalog/contracts";
+import { defineFirstPartyPluginPackage } from "@thinkwork/plugin-catalog/plugin-package";
+
+import { sendgridPluginPackage } from "../src";
+import { sendgridManifest } from "../src/manifest";
+import {
+  SENDGRID_EMAIL_CHANNEL_CAPABILITY_KEY,
+  SENDGRID_SETTINGS_SURFACE,
+  sendGridEmailChannelProviders,
+} from "../src/provider-contract";
+
+function emailCapability(
+  manifest: PluginManifest = sendgridManifest as PluginManifest,
+): EmailChannelCapability {
+  const capability = manifest.versions[0].capabilities?.find(
+    (candidate) => candidate.type === "email-channel",
+  );
+  if (capability?.type !== "email-channel") {
+    throw new Error(
+      "SendGrid manifest is missing its email-channel capability",
+    );
+  }
+  return capability;
+}
+
+describe("SendGrid plugin manifest", () => {
+  it("validates as a standalone email provider plugin", () => {
+    const validated = validatePluginManifest(sendgridManifest);
+
+    expect(validated.pluginKey).toBe("sendgrid");
+    expect(validated.displayName).toBe("SendGrid Email");
+    expect(validated.versions[0].requiredOauthScopes).toEqual([]);
+    expect(validated.versions[0].components).toEqual([
+      {
+        type: "ui-surface",
+        key: "settings",
+        displayName: "SendGrid Email settings",
+        intendedMount: SENDGRID_SETTINGS_SURFACE,
+      },
+    ]);
+  });
+
+  it("declares only the SendGrid provider option", () => {
+    expect(sendGridEmailChannelProviders).toEqual([
+      {
+        key: "sendgrid",
+        displayName: "SendGrid",
+        recommended: true,
+      },
+    ]);
+
+    const capability = emailCapability();
+    expect(capability).toMatchObject({
+      type: "email-channel",
+      key: SENDGRID_EMAIL_CHANNEL_CAPABILITY_KEY,
+      settingsSurface: SENDGRID_SETTINGS_SURFACE,
+    });
+    expect(capability.providers).toEqual(sendGridEmailChannelProviders);
+  });
+
+  it("defines a first-party package boundary under plugins/sendgrid", () => {
+    const defined = defineFirstPartyPluginPackage(sendgridPluginPackage);
+
+    expect(defined.packageKey).toBe("sendgrid");
+    expect(defined.sourceRoot).toBe("plugins/sendgrid");
+    expect(defined.ownedSources).toContainEqual({
+      kind: "manifest",
+      path: "plugins/sendgrid/src/manifest.ts",
+      description:
+        "SendGrid Email catalog manifest and provider capability contract.",
+    });
+    expect(defined.compatibilityLinks).toEqual([]);
+  });
+});

package/dist/plugins/sendgrid/tsconfig.json

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

package/dist/plugins/twenty/README.md

@@ -0,0 +1,78 @@
+# Twenty Plugin
+
+Twenty CRM is a first-party application plugin package for the THNK-31
+`plugins/<plugin-key>/` source boundary. It owns the Twenty catalog manifest,
+managed-app/MCP smoke contracts, package tests, and migration notes for the
+remaining infrastructure and activation source.
+
+## Package Contract
+
+- `package.json` exposes `@thinkwork/plugin-twenty`.
+- `src/index.ts` exports `twentyPluginPackage` with owned source descriptors
+  and compatibility links.
+- `src/manifest.ts` owns the Twenty catalog manifest.
+- `src/deployment/managed-app.ts` owns the Twenty managed-app deployment
+  adapter.
+- `src/api/cutover.ts` owns the Twenty MCP cutover orchestration contract.
+- The latest manifest version also declares the `client-engagement`
+  `ui-surface` component. Updating an installed Twenty plugin to that version
+  records a provisioned no-op UI component; the day-to-day app launches from the
+  main ThinkWork `Apps` surface, not from Settings.
+- `twenty-app/` owns the native Twenty app source package. It installs as an
+  application named `ThinkWork` and exposes a logic function named
+  `ThinkWork Webhook` as a workflow action. Its native Settings tab includes
+  a `ThinkWork Webhook` configuration form that saves the app's webhook URL and
+  trigger-stage application variables.
+- `terraform/twenty/` owns the Twenty managed-app Terraform module.
+- `smoke/` owns Twenty managed-app and MCP OAuth smoke scripts.
+- `test/manifest.test.ts` keeps Twenty endpoint, OAuth, infrastructure, and
+  managed-app input contracts aligned, including the presence of the native
+  Twenty app package.
+
+## Verification
+
+```bash
+pnpm --filter @thinkwork/plugin-twenty test
+pnpm --filter @thinkwork/plugin-twenty typecheck
+```
+
+The native Twenty app is intentionally a nested Twenty/Yarn project, not a
+pnpm workspace package. See `twenty-app/README.md` for dry-run and sync
+instructions, or use `plugins/twenty/scripts/sync-thinkwork-app.mjs` from the
+guarded deploy workflow path.
+
+The workflow wiring is also explicit and guarded. The target Twenty workflow
+must call the native `ThinkWork -> ThinkWork Webhook` action instead of the
+built-in `HTTP_REQUEST` action, with the webhook URL and trigger stage coming
+from the installed ThinkWork app settings.
+
+## Client Engagement App Surface
+
+Twenty contributes the first ThinkWork plugin app: **Client Engagement**. The
+surface is declared in the plugin manifest as a trusted bundled React app with
+route segment `client-engagement` and app key `twenty-client-engagement`.
+
+Operational split:
+
+- Settings remains the install, update, infrastructure, MCP, and reconnect
+  surface. Operators install or update Twenty from Settings, and users reconnect
+  OAuth there when readiness requires it.
+- Apps is the usage surface. When the installed Twenty plugin includes the
+  provisioned `client-engagement` `ui-surface` component, the main shell shows
+  `Apps`, and selecting Client Engagement opens
+  `/apps/twenty/client-engagement`.
+- CRM-owned records load through ThinkWork GraphQL resolvers that call the
+  authenticated Twenty plugin path on the server. Browser code must not receive
+  MCP bearer tokens, tenant-wide CRM credentials, or raw MCP endpoint secrets.
+- ThinkWork-owned engagement fields persist through plugin app overlay state,
+  not browser `localStorage`.
+
+Readiness expectations:
+
+- If the app surface is not installed, it does not appear in Apps.
+- If Twenty is installed but the runtime/MCP component is unavailable, the app
+  route renders a readiness message with an operator settings action.
+- If the current user has not connected or needs to reconnect Twenty, the app
+  route renders a plugin settings action.
+- Updating an older Twenty install to the latest manifest version is the
+  supported path for enabling the Client Engagement app on existing tenants.

package/dist/plugins/twenty/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@thinkwork/plugin-twenty",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./api/cutover": "./src/api/cutover.ts",
+    "./deployment/managed-app": "./src/deployment/managed-app.ts"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "graphql": "^16.10.0"
+  },
+  "devDependencies": {
+    "@thinkwork/deployment-runner": "workspace:*",
+    "@thinkwork/plugin-catalog": "workspace:*",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/dist/plugins/twenty/scripts/__tests__/sync-thinkwork-app.test.mjs

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildTwentyRemoteConfig,
+  dryRunTwentyCommand,
+} from "../sync-thinkwork-app.mjs";
+
+describe("sync-thinkwork-app", () => {
+  it("builds a Twenty remote config from an empty config file", () => {
+    const config = buildTwentyRemoteConfig(
+      {},
+      {
+        remoteName: "thinkwork-crm",
+        url: "https://crm.thinkwork.ai",
+        apiKey: "test-key",
+      },
+    );
+
+    expect(config).toEqual({
+      version: 1,
+      defaultRemote: "thinkwork-crm",
+      remotes: {
+        "thinkwork-crm": {
+          apiUrl: "https://crm.thinkwork.ai",
+          apiKey: "test-key",
+        },
+      },
+    });
+  });
+
+  it("preserves existing Twenty remotes while selecting the ThinkWork remote", () => {
+    const config = buildTwentyRemoteConfig(
+      {
+        version: 1,
+        defaultRemote: "local",
+        remotes: {
+          local: {
+            apiUrl: "http://localhost:2020",
+          },
+        },
+      },
+      {
+        remoteName: "thinkwork-crm",
+        url: "https://crm.thinkwork.ai",
+        apiKey: "test-key",
+      },
+    );
+
+    expect(config.defaultRemote).toBe("thinkwork-crm");
+    expect(config.remotes.local).toEqual({
+      apiUrl: "http://localhost:2020",
+    });
+    expect(config.remotes["thinkwork-crm"]).toEqual({
+      apiUrl: "https://crm.thinkwork.ai",
+      apiKey: "test-key",
+    });
+  });
+
+  it("validates remote auth in dry-run mode without calling unsupported sync dry-run", () => {
+    expect(dryRunTwentyCommand("thinkwork-crm")).toEqual([
+      "twenty",
+      "--remote",
+      "thinkwork-crm",
+      "remote:status",
+    ]);
+  });
+});

package/dist/plugins/twenty/scripts/sync-thinkwork-app.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_REMOTE = "thinkwork-crm";
+const DEFAULT_APP_DIR = "plugins/twenty/twenty-app";
+
+function parseArgs(argv) {
+  const args = {
+    appDir: process.env.TWENTY_THINKWORK_APP_DIR || DEFAULT_APP_DIR,
+    remoteName: process.env.TWENTY_THINKWORK_APP_REMOTE_NAME || DEFAULT_REMOTE,
+    dryRun: process.env.TWENTY_THINKWORK_APP_SYNC_DRY_RUN !== "0",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--app-dir") {
+      args.appDir = requireValue(argv, ++index, arg);
+    } else if (arg === "--remote-name") {
+      args.remoteName = requireValue(argv, ++index, arg);
+    } else if (arg === "--url") {
+      args.url = requireValue(argv, ++index, arg);
+    } else if (arg === "--api-key") {
+      args.apiKey = requireValue(argv, ++index, arg);
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--apply") {
+      args.dryRun = false;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  args.url ||= process.env.TWENTY_PUBLIC_URL;
+  args.apiKey ||=
+    process.env.TWENTY_DEPLOY_API_KEY || process.env.TWENTY_APP_SYNC_API_KEY;
+  return args;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return value;
+}
+
+function validateUrl(url) {
+  if (!url) {
+    throw new Error("Set TWENTY_PUBLIC_URL or pass --url.");
+  }
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+    throw new Error(`Twenty URL must be HTTPS or localhost, got ${url}.`);
+  }
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function run(command, args, options) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: {
+      ...process.env,
+      YARN_ENABLE_IMMUTABLE_INSTALLS: "false",
+    },
+    stdio: "inherit",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} exited ${result.status}.`);
+  }
+}
+
+function readTwentyConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  const rawConfig = fs.readFileSync(configPath, "utf8");
+  if (rawConfig.trim() === "") {
+    return {};
+  }
+
+  return JSON.parse(rawConfig);
+}
+
+export function buildTwentyRemoteConfig(
+  existingConfig,
+  { remoteName, url, apiKey },
+) {
+  return {
+    ...existingConfig,
+    version: existingConfig.version ?? 1,
+    defaultRemote: remoteName,
+    remotes: {
+      ...existingConfig.remotes,
+      [remoteName]: {
+        apiUrl: url,
+        apiKey,
+      },
+    },
+  };
+}
+
+function writeTwentyRemoteConfig({ remoteName, url, apiKey }) {
+  const configDir = path.join(os.homedir(), ".twenty");
+  const configPath = path.join(configDir, "config.json");
+  fs.mkdirSync(configDir, { recursive: true });
+  const existingConfig = readTwentyConfig(configPath);
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify(
+      buildTwentyRemoteConfig(existingConfig, { remoteName, url, apiKey }),
+      null,
+      2,
+    ),
+  );
+}
+
+export function dryRunTwentyCommand(remoteName) {
+  return ["twenty", "--remote", remoteName, "remote:status"];
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const url = validateUrl(args.url);
+  if (!args.apiKey) {
+    throw new Error(
+      "Set TWENTY_DEPLOY_API_KEY, TWENTY_APP_SYNC_API_KEY, or pass --api-key.",
+    );
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        app: "ThinkWork",
+        remoteName: args.remoteName,
+        url,
+        mode: args.dryRun ? "dry-run" : "apply",
+        note: args.dryRun
+          ? "Dry run validates the package and Twenty remote credentials without deploying or installing."
+          : "Apply deploys the private app package to Twenty and installs it into the target workspace.",
+      },
+      null,
+      2,
+    ),
+  );
+
+  run("corepack", ["enable"], { cwd: args.appDir });
+  run("yarn", ["install"], { cwd: args.appDir });
+  writeTwentyRemoteConfig({
+    remoteName: args.remoteName,
+    url,
+    apiKey: args.apiKey,
+  });
+
+  if (args.dryRun) {
+    run("yarn", dryRunTwentyCommand(args.remoteName), {
+      cwd: args.appDir,
+    });
+    return;
+  }
+
+  run(
+    "yarn",
+    ["twenty", "app:publish", "--private", "--remote", args.remoteName],
+    { cwd: args.appDir },
+  );
+  run("yarn", ["twenty", "app:install", "--remote", args.remoteName], {
+    cwd: args.appDir,
+  });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}