thinkwork-cli 0.12.11 → 0.12.15

package/dist/plugins/README.md

@@ -0,0 +1,162 @@
+# ThinkWork Plugin Packages
+
+`plugins/<plugin-key>/` is the canonical ownership boundary for first-party
+ThinkWork application plugin source. A maintainer should be able to open one
+plugin package and understand the plugin-specific manifest, skills, deployment
+shape, runtime assets, UI surfaces, smoke coverage, tests, and operating notes
+without hunting through shared platform packages.
+
+Shared packages still own generic infrastructure: manifest validation, catalog
+build/signing, GraphQL transport, install and activation state machines,
+deployment-runner orchestration, common web shell code, database schema, and
+common test harnesses. Plugin packages own the product-specific source that
+plugs into those contracts.
+
+The generic catalog/contract package lives at `plugins/catalog` and is still
+published inside the workspace as `@thinkwork/plugin-catalog`. It is not a
+first-party application plugin; registry generation skips it and discovers only
+real `plugins/<plugin-key>/` application packages.
+
+## Package Contract
+
+Each plugin package should include the pieces that apply to that plugin:
+
+- `package.json` and `tsconfig.json` so the package participates in the pnpm
+  workspace.
+- `src/index.ts` exporting a `FirstPartyPluginPackage` descriptor with
+  `packageKey`, `sourceRoot`, the validated manifest, owned source descriptors,
+  and temporary compatibility links.
+- `src/manifest.ts` for the versioned catalog manifest.
+- `src/api/` for plugin-specific API/runtime hooks.
+- `src/deployment/` for managed-application adapters.
+- `src/web/` for plugin-specific operator UI panels rendered by shared hosts.
+- `terraform/<managed-app-key>/` for plugin-owned Terraform source.
+- `runtime/` for plugin-owned Dockerfiles or runtime assets.
+- `smoke/` for live or dry-run smoke validation scripts.
+- `test/` for package-local contract and parity tests.
+- `README.md` for review, operation, migration debt, and verification notes.
+
+The descriptor is intentionally machine-readable so docs, release tooling,
+source-boundary checks, and plugin-builder output can agree on the same package
+shape.
+
+## Temporary Compatibility Links
+
+During THNK-31 migration, a plugin README and descriptor may reference legacy
+paths outside `plugins/<plugin-key>/` only when the path is documented as
+migration debt. Each compatibility link must explain why it remains outside the
+package and which implementation unit or release pass removes it.
+
+Compatibility links are not ownership claims. They are breadcrumbs that keep
+review honest while source moves behind the package boundary.
+
+## Shared Platform Code
+
+Do not move generic platform code into a plugin package just because a plugin
+uses it. Keep shared contracts and orchestration in the owning workspace package
+and expose a generic extension point when plugin-specific behavior needs to be
+called from shared code.
+
+## Verification
+
+For package-local changes, run the plugin package test or typecheck command:
+
+```bash
+pnpm --filter @thinkwork/plugin-<key> test
+pnpm --filter @thinkwork/plugin-<key> typecheck
+```
+
+For catalog contract changes, also run:
+
+```bash
+pnpm --filter @thinkwork/plugin-catalog test
+pnpm --filter @thinkwork/plugin-catalog typecheck
+```
+
+## Signed Catalog Publication
+
+The authored source of truth stays in root `plugins/*` packages. The runtime
+freshness channel is a signed JSON artifact produced from that source by the
+`Plugin Catalog` GitHub Actions workflow.
+
+On pull requests that touch `plugins/**`, the workflow:
+
+- checks the generated first-party plugin registry;
+- runs the catalog package tests and typecheck;
+- builds a signed catalog with an ephemeral ed25519 key; and
+- verifies the signed JSON before the PR can merge.
+
+On pushes to `main`, the workflow publishes a stable GitHub Release asset only
+when catalog-affecting source changed under `plugins/catalog/**`,
+`plugins/<plugin-key>/src/**`, or `plugins/<plugin-key>/package.json`. Docs-only
+changes under plugin folders leave the previous catalog asset in place. A manual
+workflow dispatch can force a publish when an operator needs to republish the
+current `main` catalog.
+
+The stable channel is:
+
+- release tag: `plugin-catalog-main`;
+- asset: `thinkwork-plugin-catalog-main.json`;
+- private signing secret: `PLUGIN_CATALOG_SIGNING_KEY`; and
+- signed provenance: repository, ref, source commit SHA, generated timestamp,
+  catalog digest, and per-version payload digests.
+
+The signing key is used only by GitHub Actions. Deployed ThinkWork stages should
+trust the matching public key through runtime configuration and continue to read
+catalog data through ThinkWork GraphQL, not browser-side GitHub calls.
+
+## Runtime Freshness Model
+
+Plugin authors change source under `plugins/<plugin-key>/`. The release path
+turns that source into a signed catalog artifact; the deployed API fetches that
+artifact from GitHub, verifies the signature and payload digests, and caches
+only verified snapshots. The browser never fetches GitHub directly, and the API
+never compiles or evaluates plugin TypeScript from GitHub.
+
+ThinkWork has four distinct catalog states to keep straight during review:
+
+| Layer              | Owner                                    | What changes it                                                                          |
+| ------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Authored source    | `plugins/*` package maintainers          | Pull requests that edit manifests, package metadata, skills, adapters, or runtime source |
+| Signed artifact    | GitHub Actions `Plugin Catalog` workflow | Merge to `main` with catalog-affecting plugin source, or manual workflow dispatch        |
+| API verified cache | Deployed GraphQL API                     | TTL refresh, conditional GitHub revalidation, or operator `refreshPluginCatalog`         |
+| Installed pin      | Tenant plugin install state              | `installPlugin` or `upgradePlugin` mutations through ThinkWork                           |
+
+Settings -> Plugins reads `pluginCatalog` plus `pluginCatalogMetadata` through
+GraphQL. Operators see the installed pinned version next to the latest verified
+catalog version, the source repository/tag/commit, generated and fetched
+timestamps, stale fallback status, and a `Refresh catalog` action. That action
+calls `refreshPluginCatalog`; it bypasses the API freshness TTL but still uses
+the same signature/digest verification and stale-safe fallback path.
+
+If GitHub is unavailable, rate limited, returns a malformed artifact, or serves
+an artifact with a bad signature, the API must not trust it. A previously
+verified snapshot may be served as stale fallback; otherwise the catalog fails
+closed and installed plugin state remains in Aurora.
+
+## Release And Verification Checklist
+
+When a plugin version bump should become visible without a full app deploy:
+
+1. Land the plugin source change under `plugins/*` on `main`.
+2. Confirm the `Plugin Catalog` workflow published
+   `thinkwork-plugin-catalog-main.json` on release tag `plugin-catalog-main`.
+3. Verify the signed artifact with the deployed trusted public key, or at least
+   confirm the artifact metadata contains the expected repository, ref, source
+   commit SHA, generated timestamp, catalog digest, and version payload digest.
+4. In a GitHub-backed stage, refresh the API cache by waiting for TTL or using
+   the operator `Refresh catalog` action in Settings -> Plugins.
+5. Confirm Settings -> Plugins shows the expected latest version, source
+   metadata, stale/fallback state when applicable, and update availability for
+   tenants with an older installed pin.
+6. Install or upgrade through ThinkWork. Do not substitute a direct Terraform
+   apply, vendor cloud login, local Docker Compose run, or manual catalog edit.
+7. Run the package-owned smoke for the plugin after install/upgrade. For
+   LastMile, that means proving `lastmile--crm`, `lastmile--tasks`, and
+   `lastmile--routing` through ThinkWork's MCP proxy.
+
+Before closing a migration slice, run the source-boundary check:
+
+```bash
+node scripts/verify-plugin-source-boundary.mjs
+```

package/dist/plugins/catalog/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@thinkwork/plugin-catalog",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./catalog": "./src/catalog.ts",
+    "./contracts": "./src/contracts.ts",
+    "./plugin-package": "./src/plugin-package.ts",
+    "./plugins": "./src/registry/index.ts",
+    "./registry": "./src/registry/index.ts"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate:plugins": "tsx scripts/generate-plugin-registry.ts",
+    "check:plugins": "tsx scripts/generate-plugin-registry.ts --check",
+    "build:catalog": "tsx scripts/generate-plugin-registry.ts --check && tsx scripts/build-catalog.ts"
+  },
+  "dependencies": {
+    "@thinkwork/plugin-company-brain": "workspace:*",
+    "@thinkwork/plugin-company-data": "workspace:*",
+    "@thinkwork/plugin-company-etl": "workspace:*",
+    "@thinkwork/plugin-email-channel": "workspace:*",
+    "@thinkwork/plugin-lastmile": "workspace:*",
+    "@thinkwork/plugin-n8n": "workspace:*",
+    "@thinkwork/plugin-sendgrid": "workspace:*",
+    "@thinkwork/plugin-twenty": "workspace:*",
+    "@thinkwork/plugin-workos-auth": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/dist/plugins/catalog/scripts/build-catalog.ts

@@ -0,0 +1,120 @@
+/**
+ * Build the signed plugin catalog JSON from manifests discovered through the
+ * generated `plugins/*` package registry.
+ *
+ * Signing key input (ed25519 PKCS#8 PEM), in precedence order:
+ *   1. `--key <path>` — file containing the private key PEM
+ *   2. `PLUGIN_CATALOG_SIGNING_KEY` env var — the PEM content itself
+ *
+ * Output defaults to `dist/catalog.json` (override with `--out <path>`).
+ * Source provenance can be passed explicitly or inherited from GitHub Actions:
+ *   --source-repository / PLUGIN_CATALOG_SOURCE_REPOSITORY / GITHUB_REPOSITORY
+ *   --source-ref        / PLUGIN_CATALOG_SOURCE_REF        / GITHUB_REF_NAME / GITHUB_REF
+ *   --source-commit     / PLUGIN_CATALOG_SOURCE_COMMIT_SHA / GITHUB_SHA
+ *
+ * Usage: pnpm --filter @thinkwork/plugin-catalog build:catalog -- --key signing-key.pem
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  buildPluginCatalog,
+  signPluginCatalog,
+  type PluginCatalogSourceProvenance,
+} from "../src/catalog";
+import type { PluginManifest } from "../src/contracts";
+import { allPluginManifests } from "../src/registry";
+
+export function buildSignedCatalogJson(options: {
+  manifests: readonly PluginManifest[];
+  privateKeyPem: string;
+  generatedAt?: Date | string;
+  source?: PluginCatalogSourceProvenance;
+}): string {
+  const catalog = buildPluginCatalog({
+    manifests: options.manifests,
+    generatedAt: options.generatedAt,
+    source: options.source,
+  });
+  const document = signPluginCatalog({
+    catalog,
+    privateKeyPem: options.privateKeyPem,
+    signedAt: options.generatedAt,
+  });
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+function readArg(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  if (!value) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function readSourceProvenance(
+  argv: string[],
+): PluginCatalogSourceProvenance | undefined {
+  const repository =
+    readArg(argv, "--source-repository") ??
+    process.env.PLUGIN_CATALOG_SOURCE_REPOSITORY ??
+    process.env.GITHUB_REPOSITORY;
+  const ref =
+    readArg(argv, "--source-ref") ??
+    process.env.PLUGIN_CATALOG_SOURCE_REF ??
+    process.env.GITHUB_REF_NAME ??
+    process.env.GITHUB_REF;
+  const commitSha =
+    readArg(argv, "--source-commit") ??
+    process.env.PLUGIN_CATALOG_SOURCE_COMMIT_SHA ??
+    process.env.GITHUB_SHA;
+
+  const values = [repository, ref, commitSha].filter(Boolean);
+  if (values.length === 0) return undefined;
+  if (!repository || !ref || !commitSha) {
+    throw new Error(
+      "Catalog source provenance requires repository, ref, and commit SHA. " +
+        "Pass --source-repository, --source-ref, and --source-commit or set the matching env vars.",
+    );
+  }
+  return { repository, ref, commitSha };
+}
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  const keyPath = readArg(argv, "--key");
+  const privateKeyPem = keyPath
+    ? readFileSync(keyPath, "utf8")
+    : process.env.PLUGIN_CATALOG_SIGNING_KEY;
+  if (!privateKeyPem) {
+    console.error(
+      "Missing signing key: pass --key <pem-file> or set PLUGIN_CATALOG_SIGNING_KEY",
+    );
+    process.exit(1);
+  }
+
+  const outPath =
+    readArg(argv, "--out") ??
+    fileURLToPath(new URL("../dist/catalog.json", import.meta.url));
+  const json = buildSignedCatalogJson({
+    manifests: allPluginManifests,
+    privateKeyPem,
+    source: readSourceProvenance(argv),
+  });
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, json, "utf8");
+  console.log(
+    `Wrote signed catalog (${allPluginManifests.length} plugin${allPluginManifests.length === 1 ? "" : "s"}) to ${outPath}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main();
+}

package/dist/plugins/catalog/scripts/generate-plugin-registry.ts

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export interface PluginRegistryEntry {
+  packageKey: string;
+  packageName: string;
+  exportName: string;
+  manifestExportName: string;
+  rawExportName: string;
+}
+
+const GENERATED_PATH = new URL(
+  "../src/registry/generated-first-party.ts",
+  import.meta.url,
+);
+
+export function discoverPluginRegistryEntries({
+  repoRoot = resolve(fileURLToPath(new URL("../../..", import.meta.url))),
+} = {}): PluginRegistryEntry[] {
+  const pluginsRoot = resolve(repoRoot, "plugins");
+  return readdirSync(pluginsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const packageKey = entry.name;
+      const packageJsonPath = resolve(pluginsRoot, packageKey, "package.json");
+      if (!existsSync(packageJsonPath)) return null;
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+        name?: string;
+        thinkworkPlugin?: {
+          catalogPublication?: string;
+        };
+      };
+      if (!packageJson.name?.startsWith("@thinkwork/plugin-")) return null;
+      if (packageJson.name === "@thinkwork/plugin-catalog") return null;
+      if (packageJson.thinkworkPlugin?.catalogPublication === "deferred") {
+        return null;
+      }
+      const exportName = `${camelCase(packageKey)}PluginPackage`;
+      return {
+        packageKey,
+        packageName: packageJson.name,
+        exportName,
+        manifestExportName: `${camelCase(packageKey)}Manifest`,
+        rawExportName: `raw${pascalCase(packageKey)}PluginPackage`,
+      };
+    })
+    .filter((entry): entry is PluginRegistryEntry => entry !== null)
+    .sort((a, b) => a.packageKey.localeCompare(b.packageKey));
+}
+
+export function renderPluginRegistry(entries: readonly PluginRegistryEntry[]) {
+  const imports = entries
+    .map(
+      (entry) =>
+        `import { ${entry.exportName} as ${entry.rawExportName} } from "${entry.packageName}";`,
+    )
+    .join("\n");
+  const packages = entries
+    .map(
+      (entry) =>
+        `export const ${entry.exportName} = defineFirstPartyPluginPackage(
+  ${entry.rawExportName},
+);`,
+    )
+    .join("\n");
+  const manifests = entries
+    .map(
+      (entry) =>
+        `export const ${entry.manifestExportName} = ${entry.exportName}.manifest;`,
+    )
+    .join("\n");
+  const packageList = entries
+    .map((entry) => `  ${entry.exportName},`)
+    .join("\n");
+
+  return `// Generated by plugins/catalog/scripts/generate-plugin-registry.ts.
+// Do not edit by hand. Update plugins/*/package.json, then run:
+//   pnpm --filter @thinkwork/plugin-catalog generate:plugins
+
+import { defineFirstPartyPluginPackage } from "../plugin-package";
+${imports}
+
+${packages}
+
+${manifests}
+
+export const firstPartyPluginPackages = [
+${packageList}
+] as const;
+
+/**
+ * Every repo-authored manifest published to the catalog.
+ */
+export const allPluginManifests = firstPartyPluginPackages
+  .map((pluginPackage) => pluginPackage.manifest)
+  .sort((a, b) => {
+    const byName = a.displayName.localeCompare(b.displayName, undefined, {
+      sensitivity: "base",
+    });
+    return byName === 0 ? a.pluginKey.localeCompare(b.pluginKey) : byName;
+  });
+`;
+}
+
+export function expectedPluginRegistry({
+  repoRoot,
+}: { repoRoot?: string } = {}) {
+  return renderPluginRegistry(discoverPluginRegistryEntries({ repoRoot }));
+}
+
+function camelCase(value: string) {
+  return value.replace(/-([a-z0-9])/g, (_match, char: string) =>
+    char.toUpperCase(),
+  );
+}
+
+function pascalCase(value: string) {
+  const camel = camelCase(value);
+  return `${camel[0]?.toUpperCase() ?? ""}${camel.slice(1)}`;
+}
+
+function main() {
+  const generatedPath = fileURLToPath(GENERATED_PATH);
+  const expected = expectedPluginRegistry();
+  if (process.argv.includes("--check")) {
+    const actual = readFileSync(generatedPath, "utf8");
+    if (actual !== expected) {
+      throw new Error(
+        `${generatedPath} is stale; run pnpm --filter @thinkwork/plugin-catalog generate:plugins`,
+      );
+    }
+    return;
+  }
+  writeFileSync(generatedPath, expected, "utf8");
+  console.log(`Wrote ${generatedPath}`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main();
+}

package/dist/plugins/catalog/src/__tests__/build-catalog.test.ts

@@ -0,0 +1,86 @@
+import { generateKeyPairSync } from "node:crypto";
+import { describe, expect, it } from "vitest";
+
+import { buildSignedCatalogJson } from "../../scripts/build-catalog";
+import { verifyPluginCatalog } from "../catalog";
+import { allPluginManifests } from "../registry";
+
+function keyPair() {
+  const pair = generateKeyPairSync("ed25519");
+  return {
+    publicKeyPem: pair.publicKey.export({
+      format: "pem",
+      type: "spki",
+    }) as string,
+    privateKeyPem: pair.privateKey.export({
+      format: "pem",
+      type: "pkcs8",
+    }) as string,
+  };
+}
+
+describe("buildSignedCatalogJson", () => {
+  it("produces a JSON document that verifies against the signing key", () => {
+    const keys = keyPair();
+    const json = buildSignedCatalogJson({
+      manifests: allPluginManifests,
+      privateKeyPem: keys.privateKeyPem,
+      generatedAt: "2026-06-12T00:00:00.000Z",
+    });
+    const document = JSON.parse(json) as unknown;
+    const verified = verifyPluginCatalog({
+      document,
+      trustedPublicKeyPem: keys.publicKeyPem,
+    });
+    expect(verified.plugins.map((plugin) => plugin.pluginKey)).toEqual([
+      "lastmile",
+      "n8n",
+      "email-channel",
+      "sendgrid",
+      "company-brain",
+      "company-data",
+      "company-etl",
+      "twenty",
+      "workos-auth",
+    ]);
+    expect(verified.generatedAt).toBe("2026-06-12T00:00:00.000Z");
+  });
+
+  it("includes source provenance when provided by the publisher", () => {
+    const keys = keyPair();
+    const json = buildSignedCatalogJson({
+      manifests: allPluginManifests,
+      privateKeyPem: keys.privateKeyPem,
+      generatedAt: "2026-06-12T00:00:00.000Z",
+      source: {
+        repository: "thinkwork-ai/thinkwork",
+        ref: "main",
+        commitSha: "0123456789abcdef0123456789abcdef01234567",
+      },
+    });
+    const verified = verifyPluginCatalog({
+      document: JSON.parse(json) as unknown,
+      trustedPublicKeyPem: keys.publicKeyPem,
+    });
+    expect(verified.source).toEqual({
+      repository: "thinkwork-ai/thinkwork",
+      ref: "main",
+      commitSha: "0123456789abcdef0123456789abcdef01234567",
+    });
+  });
+
+  it("fails verification against a different key", () => {
+    const signing = keyPair();
+    const other = keyPair();
+    const json = buildSignedCatalogJson({
+      manifests: allPluginManifests,
+      privateKeyPem: signing.privateKeyPem,
+    });
+    expect(() =>
+      verifyPluginCatalog({
+        document: JSON.parse(json) as unknown,
+        trustedPublicKeyPem: other.publicKeyPem,
+      }),
+    ).toThrow(/signature is invalid/);
+  });
+});