terramend 0.2.0

package/src/utils/todoTracking.ts

@@ -0,0 +1,167 @@
+import { log } from "#app/utils/log";
+
+type TodoItem = {
+  id: string;
+  content: string;
+  status: "pending" | "in_progress" | "completed" | "cancelled";
+};
+
+function isValidTodoStatus(value: string): value is TodoItem["status"] {
+  return (
+    value === "pending" || value === "in_progress" || value === "completed" || value === "cancelled"
+  );
+}
+
+function parseTodowriteInput(input: unknown): { todos: unknown[]; merge: boolean } | undefined {
+  if (!input || typeof input !== "object" || !("todos" in input)) return undefined;
+  if (!Array.isArray(input.todos)) return undefined;
+  const merge = "merge" in input && input.merge === true;
+  return { todos: input.todos, merge };
+}
+
+function parseTodoItem(entry: unknown, index: number): TodoItem | undefined {
+  if (!entry || typeof entry !== "object") return undefined;
+  if (!("content" in entry) || typeof entry.content !== "string") return undefined;
+  const id = "id" in entry && typeof entry.id === "string" ? entry.id : String(index);
+  const status =
+    "status" in entry && typeof entry.status === "string" && isValidTodoStatus(entry.status)
+      ? entry.status
+      : "pending";
+  return { id, content: entry.content, status };
+}
+
+function renderTodoMarkdown(todos: TodoItem[]): string {
+  return todos
+    .map((todo) => {
+      switch (todo.status) {
+        case "completed":
+          return `- [x] ${todo.content}`;
+        case "cancelled":
+          return `- ~~${todo.content}~~`;
+        case "in_progress":
+          return `- [ ] <img src="https://uploads.terramend.com/Progress%20Indicator.gif"  width="11" style="visibility: visible; max-width: 100%;" />  ${todo.content}`;
+        case "pending":
+          return `- [ ] ${todo.content}`;
+        default:
+          todo.status satisfies never;
+          return `- [ ] ${todo.content}`;
+      }
+    })
+    .join("\n");
+}
+
+export type TodoTracker = {
+  update: (input: unknown) => void;
+  flush: () => Promise<void>;
+  cancel: () => void;
+  /** resolves when any in-flight onUpdate call completes */
+  settled: () => Promise<void>;
+  /** mark in-progress items as completed (for final snapshot before review/progress post) */
+  completeInProgress: () => void;
+  renderCollapsible: (options?: { completeInProgress?: boolean }) => string;
+  readonly enabled: boolean;
+  /** true after the tracker has successfully called onUpdate at least once */
+  readonly hasPublished: boolean;
+};
+
+const DEBOUNCE_MS = 2000;
+
+export function createTodoTracker(onUpdate: (body: string) => Promise<void>): TodoTracker {
+  const state = new Map<string, TodoItem>();
+  let enabled = true;
+  let hasPublished = false;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let inflightPromise: Promise<void> = Promise.resolve();
+
+  function scheduleUpdate() {
+    if (!enabled) return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      if (!enabled || state.size === 0) return;
+      const markdown = renderTodoMarkdown(Array.from(state.values()));
+      inflightPromise = inflightPromise
+        .then(async () => {
+          if (!enabled) return;
+          await onUpdate(markdown);
+          hasPublished = true;
+        })
+        .catch((err) => {
+          log.debug(`todo progress update failed: ${err}`);
+        });
+    }, DEBOUNCE_MS);
+  }
+
+  return {
+    update(input: unknown) {
+      if (!enabled) return;
+      const parsed = parseTodowriteInput(input);
+      if (!parsed) return;
+      if (!parsed.merge) state.clear();
+      for (const [index, entry] of parsed.todos.entries()) {
+        const item = parseTodoItem(entry, index);
+        if (item) state.set(item.id, item);
+      }
+      log.debug(`» todowrite: ${state.size} items tracked`);
+      scheduleUpdate();
+    },
+
+    async flush() {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (!enabled || state.size === 0) return;
+      const markdown = renderTodoMarkdown(Array.from(state.values()));
+      inflightPromise = inflightPromise
+        .then(async () => {
+          if (!enabled) return;
+          await onUpdate(markdown);
+          hasPublished = true;
+        })
+        .catch((err) => {
+          log.debug(`todo progress flush failed: ${err}`);
+        });
+      await inflightPromise;
+    },
+
+    cancel() {
+      enabled = false;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+    },
+
+    async settled() {
+      await inflightPromise;
+    },
+
+    completeInProgress() {
+      for (const item of state.values()) {
+        if (item.status === "in_progress") item.status = "completed";
+      }
+    },
+
+    renderCollapsible(options?: { completeInProgress?: boolean }): string {
+      if (state.size === 0) return "";
+      const shouldCompleteInProgress = options?.completeInProgress === true;
+      const todos = Array.from(state.values()).map((item) =>
+        shouldCompleteInProgress && item.status === "in_progress"
+          ? { ...item, status: "completed" as const }
+          : item,
+      );
+      const completed = todos.filter((t) => t.status === "completed").length;
+      const markdown = renderTodoMarkdown(todos);
+      return `<details>\n<summary>Task list (${completed}/${todos.length} completed)</summary>\n\n${markdown}\n\n</details>`;
+    },
+
+    get enabled() {
+      return enabled;
+    },
+
+    get hasPublished() {
+      return hasPublished;
+    },
+  };
+}

package/src/utils/token.test.ts

@@ -0,0 +1,239 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const getInputMock = vi.fn((_name: string): string => "");
+const setSecretMock = vi.fn();
+const acquireNewTokenMock = vi.fn();
+const onExitSignalMock = vi.fn((_handler: unknown) => removeSignalHandlerMock);
+const removeSignalHandlerMock = vi.fn();
+
+vi.mock("@actions/core", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@actions/core")>()),
+  getInput: (name: string) => getInputMock(name),
+  setSecret: (value: string) => setSecretMock(value),
+}));
+
+vi.mock("#app/utils/github", () => ({
+  acquireNewToken: (opts: unknown) => acquireNewTokenMock(opts),
+}));
+
+const globalsState = { isGitHubActions: true };
+
+vi.mock("#app/utils/globals", () => ({
+  get isGitHubActions() {
+    return globalsState.isGitHubActions;
+  },
+}));
+
+vi.mock("#app/utils/exitHandler", () => ({
+  onExitSignal: (handler: unknown) => onExitSignalMock(handler),
+}));
+
+// resolveTokens guards module-level token state with an assert, so each test
+// imports a fresh module instance.
+async function loadToken() {
+  vi.resetModules();
+  return await import("#app/utils/token");
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+  vi.stubGlobal("fetch", fetchMock);
+  vi.stubEnv("GH_TOKEN", "");
+  vi.stubEnv("GITHUB_TOKEN", "");
+  vi.stubEnv("GITHUB_API_URL", "");
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+  globalsState.isGitHubActions = true;
+});
+
+describe("getJobToken", () => {
+  it("prefers the workflow token input", async () => {
+    const { getJobToken } = await loadToken();
+    getInputMock.mockReturnValueOnce("input-token");
+    vi.stubEnv("GH_TOKEN", "gh-token");
+    expect(getJobToken()).toBe("input-token");
+  });
+
+  it("falls back to GH_TOKEN when the input is empty", async () => {
+    const { getJobToken } = await loadToken();
+    vi.stubEnv("GH_TOKEN", "gh-token");
+    vi.stubEnv("GITHUB_TOKEN", "actions-token");
+    expect(getJobToken()).toBe("gh-token");
+  });
+
+  it("falls back to GITHUB_TOKEN when GH_TOKEN is unset", async () => {
+    const { getJobToken } = await loadToken();
+    vi.stubEnv("GITHUB_TOKEN", "actions-token");
+    expect(getJobToken()).toBe("actions-token");
+  });
+
+  it("throws when no token source is available", async () => {
+    const { getJobToken } = await loadToken();
+    expect(() => getJobToken()).toThrow("token input is required");
+  });
+});
+
+describe("resolveTokens with external GH_TOKEN", () => {
+  it("uses the external token for both git and MCP and masks it", async () => {
+    const token = await loadToken();
+    vi.stubEnv("GH_TOKEN", "external-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    expect(ref.gitToken).toBe("external-token");
+    expect(ref.mcpToken).toBe("external-token");
+    expect(setSecretMock).toHaveBeenCalledWith("external-token");
+    expect(acquireNewTokenMock).not.toHaveBeenCalled();
+    expect(token.getGitHubInstallationToken()).toBe("external-token");
+
+    await ref[Symbol.asyncDispose]();
+    // dispose clears the stored value but does NOT revoke the user's own token
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(() => token.getGitHubInstallationToken()).toThrow(/tokens not set/);
+  });
+});
+
+describe("resolveTokens with acquired installation tokens", () => {
+  it("acquires a read-only git token when push is disabled", async () => {
+    const token = await loadToken();
+    acquireNewTokenMock.mockResolvedValueOnce("git-token").mockResolvedValueOnce("mcp-token");
+
+    const ref = await token.resolveTokens({ push: "disabled" });
+    expect(acquireNewTokenMock).toHaveBeenNthCalledWith(1, {
+      permissions: { contents: "read" },
+    });
+    expect(ref.gitToken).toBe("git-token");
+    expect(ref.mcpToken).toBe("mcp-token");
+    await ref[Symbol.asyncDispose]();
+  });
+
+  it("acquires a write git token (with workflows) when push is enabled", async () => {
+    const token = await loadToken();
+    acquireNewTokenMock.mockResolvedValueOnce("git-token").mockResolvedValueOnce("mcp-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    expect(acquireNewTokenMock).toHaveBeenNthCalledWith(1, {
+      permissions: { contents: "write", workflows: "write" },
+    });
+    expect(acquireNewTokenMock).toHaveBeenNthCalledWith(2, {
+      permissions: {
+        contents: "write",
+        pull_requests: "write",
+        issues: "write",
+        checks: "read",
+        actions: "read",
+      },
+    });
+    expect(setSecretMock).toHaveBeenCalledWith("git-token");
+    expect(setSecretMock).toHaveBeenCalledWith("mcp-token");
+    expect(token.getGitHubInstallationToken()).toBe("mcp-token");
+    await ref[Symbol.asyncDispose]();
+  });
+
+  it("skips secret masking outside GitHub Actions", async () => {
+    const token = await loadToken();
+    globalsState.isGitHubActions = false;
+    acquireNewTokenMock.mockResolvedValueOnce("git-token").mockResolvedValueOnce("mcp-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    expect(setSecretMock).not.toHaveBeenCalled();
+    await ref[Symbol.asyncDispose]();
+  });
+
+  it("skips masking the external token outside GitHub Actions", async () => {
+    const token = await loadToken();
+    globalsState.isGitHubActions = false;
+    vi.stubEnv("GH_TOKEN", "external-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    expect(setSecretMock).not.toHaveBeenCalled();
+    await ref[Symbol.asyncDispose]();
+  });
+
+  it("rejects a second resolveTokens call while tokens are live", async () => {
+    const token = await loadToken();
+    acquireNewTokenMock.mockResolvedValue("some-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    await expect(token.resolveTokens({ push: "enabled" })).rejects.toThrow(
+      /tokens are already resolved/,
+    );
+    await ref[Symbol.asyncDispose]();
+  });
+
+  it("dispose revokes both tokens and removes the exit-signal handler", async () => {
+    const token = await loadToken();
+    acquireNewTokenMock.mockResolvedValueOnce("git-token").mockResolvedValueOnce("mcp-token");
+
+    const ref = await token.resolveTokens({ push: "restricted" });
+    expect(onExitSignalMock).toHaveBeenCalledTimes(1);
+
+    await ref[Symbol.asyncDispose]();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const tokensRevoked = fetchMock.mock.calls.map(
+      (call) => (call[1] as RequestInit).headers as Record<string, string>,
+    );
+    expect(tokensRevoked.map((h) => h.Authorization).sort()).toEqual([
+      "Bearer git-token",
+      "Bearer mcp-token",
+    ]);
+    expect(removeSignalHandlerMock).toHaveBeenCalledTimes(1);
+    expect(() => token.getGitHubInstallationToken()).toThrow(/tokens not set/);
+  });
+
+  it("concurrent dispose calls share the in-flight revocation", async () => {
+    const token = await loadToken();
+    acquireNewTokenMock.mockResolvedValueOnce("git-token").mockResolvedValueOnce("mcp-token");
+
+    const ref = await token.resolveTokens({ push: "enabled" });
+    await Promise.all([ref[Symbol.asyncDispose](), ref[Symbol.asyncDispose]()]);
+
+    // 2 revocations total, not 4 — the second dispose awaited the first
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("revokeGitHubInstallationToken", () => {
+  it("DELETEs the installation token with auth headers", async () => {
+    const { revokeGitHubInstallationToken } = await loadToken();
+    await revokeGitHubInstallationToken("revoke-me");
+
+    expect(fetchMock).toHaveBeenCalledWith("https://api.github.com/installation/token", {
+      method: "DELETE",
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: "Bearer revoke-me",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    });
+  });
+
+  it("honors GITHUB_API_URL for GitHub Enterprise Server", async () => {
+    const { revokeGitHubInstallationToken } = await loadToken();
+    vi.stubEnv("GITHUB_API_URL", "https://ghe.example.com/api/v3");
+    await revokeGitHubInstallationToken("revoke-me");
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://ghe.example.com/api/v3/installation/token",
+      expect.objectContaining({ method: "DELETE" }),
+    );
+  });
+
+  it("swallows revocation failures instead of throwing", async () => {
+    const { revokeGitHubInstallationToken } = await loadToken();
+    fetchMock.mockRejectedValueOnce(new Error("network down"));
+    await expect(revokeGitHubInstallationToken("revoke-me")).resolves.toBeUndefined();
+  });
+
+  it("swallows non-Error revocation rejections too", async () => {
+    const { revokeGitHubInstallationToken } = await loadToken();
+    fetchMock.mockRejectedValueOnce("string failure");
+    await expect(revokeGitHubInstallationToken("revoke-me")).resolves.toBeUndefined();
+  });
+});

package/src/utils/token.ts

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import * as core from "@actions/core";
+import type { PushPermission } from "#app/external";
+import { log } from "#app/utils/cli";
+import { onExitSignal } from "#app/utils/exitHandler";
+import { acquireNewToken } from "#app/utils/github";
+import { isGitHubActions } from "#app/utils/globals";
+
+// re-export for `terramend gha token` subcommand
+export {
+  acquireNewToken as acquireInstallationToken,
+  revokeGitHubInstallationToken as revokeInstallationToken,
+};
+
+// store MCP token in memory for getGitHubInstallationToken()
+let mcpTokenValue: string | undefined;
+
+/**
+ * get the job-scoped token from action input.
+ * this token has permissions defined by the workflow's permissions block.
+ *
+ * fallback order:
+ * 1. INPUT_TOKEN (from workflow `with: token:`)
+ * 2. GH_TOKEN (external token override)
+ * 3. GITHUB_TOKEN (pre-acquired in tests or from GHA env)
+ */
+export function getJobToken(): string {
+  const inputToken = core.getInput("token");
+  if (inputToken) {
+    return inputToken;
+  }
+
+  // fallback for test environment and local dev
+  const fallbackToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  if (fallbackToken) {
+    return fallbackToken;
+  }
+
+  throw new Error("token input is required");
+}
+
+export type TokenRef = {
+  gitToken: string;
+  mcpToken: string;
+  [Symbol.asyncDispose]: () => Promise<void>;
+};
+
+type ResolveTokensParams = {
+  push: PushPermission;
+};
+
+/**
+ * resolve tokens for the action run.
+ *
+ * creates two separate tokens:
+ * - gitToken: contents permission based on `push` setting (assumed exfiltratable)
+ *   - push: enabled → contents:write (can push)
+ *   - push: disabled → contents:read (read-only)
+ * - mcpToken: full installation token - used for GitHub API calls in MCP tools (not exfiltratable)
+ *
+ * security-conscious users can pass their own token via GH_TOKEN env var or inputs.token.
+ */
+export async function resolveTokens(params: ResolveTokensParams): Promise<TokenRef> {
+  assert(!mcpTokenValue, "tokens are already resolved");
+
+  const externalToken = process.env.GH_TOKEN;
+
+  // external token takes precedence - use for both git and MCP
+  if (externalToken) {
+    mcpTokenValue = externalToken;
+
+    if (isGitHubActions) {
+      core.setSecret(externalToken);
+    }
+
+    log.info("» using external GH_TOKEN for both git and MCP");
+
+    return {
+      gitToken: externalToken,
+      mcpToken: externalToken,
+      async [Symbol.asyncDispose]() {
+        mcpTokenValue = undefined;
+        // GH_TOKEN isn't acquired here, so it's not revoked here either
+      },
+    };
+  }
+
+  // create git token based on push permission (assumed exfiltratable)
+  // disabled = read-only, restricted/enabled = write (MCP tools enforce branch restrictions)
+  // workflows permission is write-only in the API, so only requested when pushing is allowed
+  const gitPermissions =
+    params.push === "disabled"
+      ? { contents: "read" as const }
+      : { contents: "write" as const, workflows: "write" as const };
+  const gitToken = await acquireNewToken({ permissions: gitPermissions });
+  if (isGitHubActions) {
+    core.setSecret(gitToken);
+  }
+  log.info(
+    `» acquired git token (${Object.entries(gitPermissions)
+      .map((e) => e.join(":"))
+      .join(", ")})`,
+  );
+
+  // MCP token scoped to only what MCP tools actually need.
+  // not exfiltratable (only accessible via MCP tools), but scoped as defense-in-depth
+  // so even a compromised tool context can't touch secrets, admin, etc.
+  const mcpPermissions = {
+    contents: "write",
+    pull_requests: "write",
+    issues: "write",
+    checks: "read",
+    actions: "read",
+  } as const;
+  const mcpToken = await acquireNewToken({ permissions: mcpPermissions });
+  if (isGitHubActions) {
+    core.setSecret(mcpToken);
+  }
+  log.info(
+    `» acquired scoped MCP token (${Object.entries(mcpPermissions)
+      .map((e) => e.join(":"))
+      .join(", ")})`,
+  );
+
+  mcpTokenValue = mcpToken;
+
+  let disposingRef: PromiseWithResolvers<void> | undefined;
+
+  const dispose = async () => {
+    if (disposingRef) {
+      // this can happen if the signal arrives when disposing tokens
+      // we make sure to wait for the current dispose to complete
+      return disposingRef.promise;
+    }
+    disposingRef = Promise.withResolvers();
+    try {
+      mcpTokenValue = undefined;
+      // revoke both tokens
+      await Promise.all([
+        revokeGitHubInstallationToken(gitToken),
+        revokeGitHubInstallationToken(mcpToken),
+      ]);
+    } finally {
+      removeSignalHandler();
+      disposingRef.resolve();
+      disposingRef = undefined;
+    }
+  };
+
+  const removeSignalHandler = onExitSignal(dispose);
+
+  return {
+    gitToken,
+    mcpToken,
+    [Symbol.asyncDispose]: dispose,
+  };
+}
+
+/**
+ * get the MCP token from memory.
+ * this is the token used for GitHub API calls in MCP tools.
+ */
+export function getGitHubInstallationToken(): string {
+  assert(mcpTokenValue, "tokens not set. call resolveTokens first.");
+  return mcpTokenValue;
+}
+
+export async function revokeGitHubInstallationToken(token: string): Promise<void> {
+  const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com";
+
+  try {
+    await fetch(`${apiUrl}/installation/token`, {
+      method: "DELETE",
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    });
+    log.debug("» installation token revoked");
+  } catch (error) {
+    log.info(
+      `Failed to revoke installation token: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/utils/version.ts

@@ -0,0 +1,10 @@
+import semver from "semver";
+import packageJson from "#package.json" with { type: "json" };
+
+export function getDevDependencyVersion(name: keyof typeof packageJson.devDependencies): string {
+  const version = packageJson.devDependencies[name];
+  if (!semver.valid(version)) {
+    throw new Error(`dev dependency "${name}" must be a pinned version, got "${version}"`);
+  }
+  return version;
+}

package/src/utils/versioning.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { validateCompatibility } from "#app/utils/versioning";
+
+describe("validateCompatibility", () => {
+  it("should throw if payload version is invalid", () => {
+    expect(() => validateCompatibility("invalid", "1.0.0")).toThrow(/not a valid semantic version/);
+  });
+
+  it.each([
+    ["1.0.0", "1.0.0"], // same
+    ["1.0.0-alpha.1", "1.0.0"], // action is newer than pre-release
+    ["0.1.0", "0.1.1"], // action is newer during active development
+    ["0.0.158", "0.0.158"], // bug #129
+    ["0.0.159", "0.0.158"], // bug #129
+    ["0.0.158", "0.0.159"], // bug #129
+    ["1.0.0", "1.0.1"], // action patched
+    ["1.0.0", "1.1.0"], // action has a new feature (backward compatible)
+    ["1.0.1", "1.0.0"], // payload is newer (patch)
+    ["1.1.0", "1.0.0"], // payload is newer (feature is backward compatible)
+  ])("should accept compatible payload %#", (payloadVersion, actionVersion) => {
+    expect(() => validateCompatibility(payloadVersion, actionVersion)).not.toThrow();
+  });
+
+  it.each([
+    ["0.1.0", "0.2.0"], // action had breaking changes during active development
+    ["0.2.0", "0.1.0"], // payload had breaking changes during active development
+    ["2.0.0", "1.0.0"], // payload is majorly newer
+    ["1.0.0", "2.0.0"], // action had breaking changes
+  ])("should reject incompatible payload %#", (payloadVersion, actionVersion) => {
+    expect(() => validateCompatibility(payloadVersion, actionVersion)).toThrow(
+      /is incompatible with action version/,
+    );
+  });
+});

package/src/utils/versioning.ts

@@ -0,0 +1,44 @@
+import semver from "semver";
+
+type CompatibilityPolicy =
+  /**
+   * Strict policy: the action must support the same features as the payload version declares
+   * @example Payload version 1.2.3 => ^1.2.0 range of action versions supported
+   * @example Payload version 0.1.55 => ^0.1.55 range of action versions supported
+   */
+  | "same-features"
+  /**
+   * Loose policy: the action must have no breaking changes compared to the payload version
+   * @example Payload version 1.2.3 => ^1.0.0 range of action versions supported
+   * @example Payload version 0.1.55 => ^0.1.0 range of action versions supported
+   */
+  | "non-breaking";
+
+const COMPATIBILITY_POLICY: CompatibilityPolicy = "non-breaking";
+
+/**
+ * @throws Error if the action can't process payload
+ * The compatibility is determined according to the COMPATIBILITY_POLICY above.
+ * @param payloadVersion the version of the payload
+ * @param actionVersion the version of the action (recipient)
+ */
+export function validateCompatibility(payloadVersion: string, actionVersion: string): void {
+  const payloadSemVer = semver.parse(payloadVersion);
+  if (!payloadSemVer)
+    throw new Error(`Payload version ${payloadVersion} is not a valid semantic version.`);
+  const major = payloadSemVer.major;
+  const minor = payloadSemVer.minor;
+  const patch = payloadSemVer.patch;
+
+  const compatibilityRange =
+    COMPATIBILITY_POLICY === "same-features"
+      ? `^${major}.${minor}.${major === 0 ? patch : 0}`
+      : `^${major}.${major === 0 ? minor : 0}.${major === 0 ? "x" : 0}`; // non-breaking
+
+  if (!semver.satisfies(actionVersion, compatibilityRange)) {
+    throw new Error(
+      `Payload version ${payloadVersion} is incompatible with action version ${actionVersion}. ` +
+        `Please update your workflow to use at least ${semver.minVersion(compatibilityRange)} version of the action.`,
+    );
+  }
+}