@sentry/junior-vercel 0.108.0 → 0.109.0

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-vercel
 
-`@sentry/junior-vercel` adds read-only Vercel deployment and log investigation workflows to Junior through the Vercel CLI.
+`@sentry/junior-vercel` adds read-only Vercel deployment and log investigation workflows through the Vercel CLI. Signed Vercel webhooks can also notify an existing Junior conversation when a deployment succeeds, fails, or is canceled.
 
 ## Install
 
@@ -10,12 +10,13 @@ pnpm add @sentry/junior @sentry/junior-vercel
 
 ## Configure
 
-Add the package name to the plugin set exported from `plugins.ts`:
+Add the plugin factory to the plugin set exported from `plugins.ts`:
 
 ```ts
 import { defineJuniorPlugins } from "@sentry/junior";
+import { vercelPlugin } from "@sentry/junior-vercel";
 
-export const plugins = defineJuniorPlugins(["@sentry/junior-vercel"]);
+export const plugins = defineJuniorPlugins([vercelPlugin()]);
 ```
 
 Point `juniorNitro()` at that plugin module:
@@ -32,11 +33,25 @@ JUNIOR_VERCEL_TOKEN=...
 
 Use a Vercel service account or token with the smallest project/team access that covers the deployments users need to inspect.
 
+## Optional deployment webhooks
+
+In **Vercel Team Settings → Webhooks**, create a project-scoped [account webhook](https://vercel.com/docs/webhooks#account-webhooks). Account webhooks are available for Pro and Enterprise teams.
+
+```text
+https://<junior-host>/api/webhooks/vercel
+```
+
+The endpoint must be publicly reachable. Subscribe it to `deployment.succeeded`, `deployment.error`, and `deployment.canceled`, select the projects Junior should monitor, and save the one-time secret as a sensitive `VERCEL_WEBHOOK_SECRET` value in Junior's Production environment. Redeploy Junior after adding it.
+
+Deployment watches use Vercel's canonical `prj_...` ID. Junior resolves that ID from the project name or ID and optional team slug or ID through Vercel's authenticated project API.
+
+Create the conversation watch before the terminal deployment event. A valid webhook delivery does not create a watch by itself, and unmatched deliveries are not replayed later.
+
 ## Auth model
 
 - This package uses a deployment-level Vercel token, not per-user OAuth.
 - Junior keeps the real `JUNIOR_VERCEL_TOKEN` host-side.
-- Matching Vercel API requests from the CLI receive a host-managed `Authorization` header.
+- Matching Vercel API requests from the CLI and plugin tools receive a host-managed `Authorization` header.
 - The sandbox receives only a non-secret placeholder `VERCEL_TOKEN` so the Vercel CLI can run normally before making API requests.
 
 ## Optional channel defaults

package/dist/chunk-GIY5FD3W.js

@@ -0,0 +1,256 @@
+// src/webhooks/secret.ts
+function vercelWebhookSecret() {
+  return process.env.VERCEL_WEBHOOK_SECRET?.trim() || void 0;
+}
+
+// src/tools/deployment-source.ts
+import {
+  definePluginTool,
+  pluginToolResultSchema,
+  subscribableResourceSchema
+} from "@sentry/junior-plugin-api";
+import { z } from "zod";
+
+// src/resource-events/deployment-source.ts
+var VERCEL_DEPLOYMENT_EVENTS = [
+  "deployment.succeeded",
+  "deployment.error",
+  "deployment.canceled"
+];
+function vercelDeploymentSourceResource(input) {
+  const commitSha2 = input.commitSha.toLowerCase();
+  return {
+    label: `Vercel ${input.target} deployment for ${input.projectId} at ${commitSha2.slice(0, 12)}`,
+    provider: "vercel",
+    resourceRef: `vercel:deployment-source:${input.projectId}:${input.target}:${commitSha2}`
+  };
+}
+function vercelDeploymentSourceSubscribable(input) {
+  if (!input.webhookSecret) return void 0;
+  return {
+    ...vercelDeploymentSourceResource(input),
+    suggestedEvents: [...VERCEL_DEPLOYMENT_EVENTS],
+    supportedEvents: [...VERCEL_DEPLOYMENT_EVENTS],
+    type: "deployment_source"
+  };
+}
+
+// src/tools/deployment-source.ts
+var projectIdSchema = z.string().regex(/^prj_[A-Za-z0-9]+$/);
+var commitShaSchema = z.string().regex(/^[0-9a-f]{40}$/i);
+var targetSchema = z.enum(["preview", "production", "staging"]);
+var nonEmptyStringSchema = z.string().trim().min(1);
+var inputSchema = z.object({
+  commitSha: commitShaSchema.describe("Full 40-character Git commit SHA."),
+  project: nonEmptyStringSchema.describe("Vercel project name or prj_ ID."),
+  target: targetSchema.describe("Deployment target to monitor.").default("production"),
+  team: nonEmptyStringSchema.describe("Optional Vercel team slug or team_ ID that owns the project.").optional()
+}).strict();
+var deploymentSourceSchema = z.object({
+  commitSha: commitShaSchema,
+  deploymentTarget: targetSchema,
+  projectId: projectIdSchema,
+  subscribable: subscribableResourceSchema.optional()
+});
+var outputSchema = pluginToolResultSchema.extend({
+  data: deploymentSourceSchema,
+  ok: z.literal(true),
+  status: z.literal("success"),
+  target: z.literal("deploymentSource"),
+  ...deploymentSourceSchema.shape
+});
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function projectLookupUrl(project, team) {
+  const url = new URL(
+    `https://api.vercel.com/v9/projects/${encodeURIComponent(project)}`
+  );
+  if (team) {
+    url.searchParams.set(team.startsWith("team_") ? "teamId" : "slug", team);
+  }
+  return url.toString();
+}
+function createVercelDeploymentSourceTool(ctx) {
+  return definePluginTool({
+    description: "Resolve a Vercel project name or ID and describe its deployment target and full Git commit SHA as a subscribable deployment source. Use the user's explicit project and team, otherwise the vercel.project and vercel.team conversation defaults. Use this after the final deployed commit is known and before waiting for a deployment outcome.",
+    inputSchema,
+    outputSchema,
+    async execute(input) {
+      const response = await ctx.egress.fetch({
+        operation: "vercel.project.get",
+        provider: "vercel",
+        request: new Request(projectLookupUrl(input.project, input.team))
+      });
+      const parsed = await readJson(response);
+      if (!response.ok) {
+        throw new Error(
+          `Vercel project lookup failed with HTTP ${response.status}`
+        );
+      }
+      const projectId = z.object({ id: projectIdSchema }).parse(parsed).id;
+      const commitSha2 = input.commitSha.toLowerCase();
+      const subscribable = vercelDeploymentSourceSubscribable({
+        commitSha: commitSha2,
+        projectId,
+        target: input.target,
+        webhookSecret: vercelWebhookSecret()
+      });
+      const data = {
+        commitSha: commitSha2,
+        deploymentTarget: input.target,
+        projectId,
+        ...subscribable ? { subscribable } : {}
+      };
+      return {
+        data,
+        ok: true,
+        status: "success",
+        target: "deploymentSource",
+        ...data
+      };
+    }
+  });
+}
+
+// src/webhooks/resource-events.ts
+import { z as z2 } from "zod";
+var projectIdSchema2 = z2.string().regex(/^prj_[A-Za-z0-9]+$/);
+var deploymentIdSchema = z2.string().regex(/^dpl_[A-Za-z0-9]+$/);
+var commitShaSchema2 = z2.string().regex(/^[0-9a-f]{40}$/i);
+var webhookEnvelopeSchema = z2.object({
+  createdAt: z2.number().finite(),
+  id: z2.string().min(1),
+  payload: z2.unknown(),
+  region: z2.unknown().optional(),
+  type: z2.string().min(1)
+}).strict();
+var deploymentPayloadSchema = z2.object({
+  alias: z2.unknown().optional(),
+  deployment: z2.object({
+    id: deploymentIdSchema,
+    meta: z2.record(z2.string(), z2.unknown()),
+    name: z2.unknown().optional(),
+    url: z2.unknown().optional()
+  }).strict(),
+  links: z2.unknown().optional(),
+  plan: z2.unknown().optional(),
+  project: z2.object({
+    id: projectIdSchema2,
+    name: z2.unknown().optional()
+  }).strict(),
+  regions: z2.unknown().optional(),
+  target: z2.string().nullable(),
+  team: z2.unknown().optional(),
+  user: z2.unknown().optional()
+}).strict().transform((payload) => ({
+  commitSha: commitSha(payload.deployment.meta),
+  deploymentId: payload.deployment.id,
+  projectId: payload.project.id,
+  target: deploymentTarget(payload.target)
+}));
+function deploymentTarget(value) {
+  if (value === null) return "preview";
+  if (value === "production" || value === "staging") return value;
+  return void 0;
+}
+function commitSha(meta) {
+  for (const key of [
+    "githubCommitSha",
+    "gitlabCommitSha",
+    "bitbucketCommitSha",
+    "gitCommitSha"
+  ]) {
+    const parsed = commitShaSchema2.safeParse(meta[key]);
+    if (parsed.success) return parsed.data.toLowerCase();
+  }
+  return void 0;
+}
+function isDeploymentEvent(value) {
+  return VERCEL_DEPLOYMENT_EVENTS.includes(
+    value
+  );
+}
+function normalizeVercelResourceEvents(args) {
+  const envelope = webhookEnvelopeSchema.safeParse(args.body);
+  if (!envelope.success || !isDeploymentEvent(envelope.data.type)) return [];
+  const payload = deploymentPayloadSchema.safeParse(envelope.data.payload);
+  if (!payload.success) return [];
+  const target = payload.data.target;
+  const sha = payload.data.commitSha;
+  if (!target || !sha) return [];
+  const resource = vercelDeploymentSourceResource({
+    commitSha: sha,
+    projectId: payload.data.projectId,
+    target
+  });
+  const eventType = envelope.data.type;
+  const deploymentId = payload.data.deploymentId;
+  const outcome = eventType === "deployment.succeeded" ? "succeeded" : eventType === "deployment.error" ? "failed" : "was canceled";
+  return [
+    {
+      eventKey: `vercel:${envelope.data.id}:${eventType}`,
+      eventType,
+      occurredAtMs: envelope.data.createdAt,
+      provider: "vercel",
+      resourceRef: resource.resourceRef,
+      terminal: true,
+      trustedSummary: `${resource.label} (${deploymentId}) ${outcome}.`
+    }
+  ];
+}
+
+// src/webhooks/handler.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyVercelSignature(body, signature, secret) {
+  if (!secret || !/^[0-9a-f]{40}$/i.test(signature)) return false;
+  const actual = Buffer.from(signature.toLowerCase());
+  const expected = Buffer.from(
+    createHmac("sha1", secret).update(body).digest("hex")
+  );
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function createVercelWebhookRoute(args) {
+  return {
+    method: "POST",
+    path: "/api/webhooks/vercel",
+    async handler(request) {
+      const rawBody = await request.text();
+      const signature = request.headers.get("x-vercel-signature") ?? "";
+      if (!verifyVercelSignature(rawBody, signature, args.webhookSecret())) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+      const body = parseJson(rawBody);
+      if (body === void 0) {
+        return new Response("Malformed Vercel webhook", { status: 400 });
+      }
+      const resourceEvents = normalizeVercelResourceEvents({ body });
+      for (const event of resourceEvents) {
+        await args.resourceEvents.publish(event);
+      }
+      return new Response(resourceEvents.length ? "Accepted" : "Ignored", {
+        status: 202
+      });
+    }
+  };
+}
+
+export {
+  vercelWebhookSecret,
+  createVercelDeploymentSourceTool,
+  normalizeVercelResourceEvents,
+  createVercelWebhookRoute
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vercel plugin runtime boundary.
+ *
+ * This package owns Vercel CLI setup, host-managed API authentication, signed
+ * webhook normalization, and deployment-source tools. Junior core owns the
+ * resulting conversation subscriptions and event delivery.
+ */
+import { type PluginRegistration } from "@sentry/junior-plugin-api";
+/** Register Vercel runtime metadata, tools, and signed webhook ingress. */
+export declare function vercelPlugin(): PluginRegistration;

package/dist/index.js

@@ -0,0 +1,58 @@
+import {
+  createVercelDeploymentSourceTool,
+  createVercelWebhookRoute,
+  vercelWebhookSecret
+} from "./chunk-GIY5FD3W.js";
+
+// src/index.ts
+import {
+  defineJuniorPlugin
+} from "@sentry/junior-plugin-api";
+function vercelPlugin() {
+  return defineJuniorPlugin({
+    packageName: "@sentry/junior-vercel",
+    manifest: {
+      apiHeaders: {
+        Authorization: "Bearer ${JUNIOR_VERCEL_TOKEN}"
+      },
+      capabilities: ["api"],
+      commandEnv: {
+        VERCEL_TOKEN: "host_managed_credential"
+      },
+      configKeys: ["project", "team"],
+      description: "Query Vercel deployments and logs and monitor deployment outcomes",
+      displayName: "Vercel",
+      domains: ["api.vercel.com"],
+      envVars: {
+        JUNIOR_VERCEL_TOKEN: {},
+        VERCEL_WEBHOOK_SECRET: {}
+      },
+      name: "vercel",
+      runtimeDependencies: [
+        {
+          package: "vercel",
+          type: "npm",
+          version: "latest"
+        }
+      ]
+    },
+    hooks: {
+      routes(ctx) {
+        return [
+          createVercelWebhookRoute({
+            resourceEvents: ctx.resourceEvents,
+            webhookSecret: vercelWebhookSecret
+          })
+        ];
+      },
+      tools(ctx) {
+        return {
+          deploymentSource: createVercelDeploymentSourceTool(ctx)
+        };
+      }
+    }
+  });
+}
+export {
+  vercelPlugin
+};

package/dist/resource-events/deployment-source.d.ts

@@ -0,0 +1,16 @@
+import type { SubscribableResource } from "@sentry/junior-plugin-api";
+export declare const VERCEL_DEPLOYMENT_EVENTS: readonly ["deployment.succeeded", "deployment.error", "deployment.canceled"];
+export type VercelDeploymentTarget = "preview" | "production" | "staging";
+/** Build the stable deployment-source identity shared by tools and webhooks. */
+export declare function vercelDeploymentSourceResource(input: {
+    commitSha: string;
+    projectId: string;
+    target: VercelDeploymentTarget;
+}): Pick<SubscribableResource, "label" | "provider" | "resourceRef">;
+/** Describe a deployment source when signed Vercel webhooks are enabled. */
+export declare function vercelDeploymentSourceSubscribable(input: {
+    commitSha: string;
+    projectId: string;
+    target: VercelDeploymentTarget;
+    webhookSecret?: string;
+}): SubscribableResource | undefined;

package/dist/testing.d.ts

@@ -0,0 +1,3 @@
+export { createVercelDeploymentSourceTool } from "./tools/deployment-source.js";
+export { createVercelWebhookRoute } from "./webhooks/handler.js";
+export { normalizeVercelResourceEvents } from "./webhooks/resource-events.js";

package/dist/testing.js

@@ -0,0 +1,10 @@
+import {
+  createVercelDeploymentSourceTool,
+  createVercelWebhookRoute,
+  normalizeVercelResourceEvents
+} from "./chunk-GIY5FD3W.js";
+export {
+  createVercelDeploymentSourceTool,
+  createVercelWebhookRoute,
+  normalizeVercelResourceEvents
+};

package/dist/tools/deployment-source.d.ts

@@ -0,0 +1,47 @@
+import { type ToolRegistrationHookContext } from "@sentry/junior-plugin-api";
+/** Resolve and return the resource identity for one Vercel deployment source. */
+export declare function createVercelDeploymentSourceTool(ctx: ToolRegistrationHookContext): import("@sentry/junior-plugin-api").PluginToolDefinition<{
+    commitSha: string;
+    project: string;
+    target: "preview" | "production" | "staging";
+    team?: string | undefined;
+}, {
+    [x: string]: unknown;
+    commitSha: string;
+    deploymentTarget: "preview" | "production" | "staging";
+    projectId: string;
+    data: {
+        commitSha: string;
+        deploymentTarget: "preview" | "production" | "staging";
+        projectId: string;
+        subscribable?: {
+            label: string;
+            provider: string;
+            resourceRef: string;
+            supportedEvents: string[];
+            type: string;
+            suggestedEvents?: string[] | undefined;
+        } | undefined;
+    };
+    ok: true;
+    status: "success";
+    target: "deploymentSource";
+    truncated?: boolean | undefined;
+    continuation?: {
+        arguments: Record<string, unknown>;
+        reason?: string | undefined;
+    } | undefined;
+    error?: string | {
+        kind: string;
+        message: string;
+        retryable?: boolean | undefined;
+    } | undefined;
+    subscribable?: {
+        label: string;
+        provider: string;
+        resourceRef: string;
+        supportedEvents: string[];
+        type: string;
+        suggestedEvents?: string[] | undefined;
+    } | undefined;
+}>;

package/dist/webhooks/handler.d.ts

@@ -0,0 +1,6 @@
+import type { PluginRoute, ResourceEventPublisher } from "@sentry/junior-plugin-api";
+/** Create the public, signed Vercel deployment webhook route. */
+export declare function createVercelWebhookRoute(args: {
+    resourceEvents: ResourceEventPublisher;
+    webhookSecret(): string | undefined;
+}): PluginRoute;

package/dist/webhooks/resource-events.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Owns Vercel's deployment webhook wire-format boundary.
+ *
+ * It validates provider payloads, ignores unsupported or incomplete deliveries,
+ * and emits only canonical terminal resource events.
+ */
+import type { ResourceEvent } from "@sentry/junior-plugin-api";
+/** Normalize one verified Vercel delivery into a terminal deployment event. */
+export declare function normalizeVercelResourceEvents(args: {
+    body: unknown;
+}): ResourceEvent[];

package/dist/webhooks/secret.d.ts

@@ -0,0 +1,2 @@
+/** Read the normalized secret shared by watch creation and webhook ingress. */
+export declare function vercelWebhookSecret(): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-vercel",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -11,8 +11,35 @@
     "url": "git+https://github.com/getsentry/junior.git",
     "directory": "packages/junior-vercel"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
   "files": [
-    "plugin.yaml",
+    "dist",
     "skills"
-  ]
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@sentry/junior-plugin-api": "0.109.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "oxlint": "^1.66.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "lint": "oxlint --config ../junior/.oxlintrc.json --deny-warnings src tests tsup.config.ts vitest.config.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/skills/vercel/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: vercel
 description: Query Vercel deployments, build logs, runtime logs, and deployment status through the Vercel CLI. Use when users ask to debug Vercel deployments, inspect failed builds, fetch production or preview runtime logs, find a deployment for a project or commit SHA, or investigate Vercel-hosted app errors. Do not use it for deploying, rolling back, changing project settings, domains, env vars, caches, storage, or any other Vercel mutation.
-allowed-tools: bash
 ---
 
 # Vercel Operations
@@ -25,7 +24,7 @@ Do not run `deploy`, `rollback`, `promote`, `remove`, `env`, `alias`, `dns`, `pr
 
 - Determine whether the user needs runtime logs, build logs, deployment status, or deployment discovery.
 - Prefer explicit deployment IDs, deployment URLs, project names, environments, branch names, commit SHAs, status filters, and time windows from the user.
-- When the user did not specify a project or team, treat `vercel.project` and `vercel.team` conversation config as optional defaults. Explicit user input always wins.
+- When the user did not specify a project or team, read `vercel.project` and `vercel.team` with `jr-rpc config get` and treat them as optional conversation defaults. Explicit user input always wins.
 - Only set or change `vercel.project` and `vercel.team` when the user explicitly asks to store a default for this conversation or channel.
 - Ask one concise follow-up only when the request cannot be bounded to a project, deployment, commit, or time window from the thread or config.
 
@@ -38,6 +37,7 @@ Do not run `deploy`, `rollback`, `promote`, `remove`, `env`, `alias`, `dns`, `pr
 - For runtime logs, prefer `vercel logs --project <project> --since <window> --limit 20 --json` plus user-provided filters such as `--environment`, `--level`, `--status-code`, `--source`, `--query`, or `--deployment`.
 - Use `vercel inspect <deployment-id-or-url> --logs` for build logs. Add `--wait` only when the user explicitly wants to wait for an active build; also bound it with `--timeout`.
 - Use `vercel list <project>` or `vercel ls <project>` to find deployments. Prefer filters such as `--status`, `--environment`, `--prod`, or `--meta githubCommitSha=<sha>` when available.
+- For a deployment watch, call the `vercel_deploymentSource` plugin tool with the project name, optional team slug or ID, deployment target, and full 40-character commit SHA. The tool resolves the canonical project ID through Vercel before Junior creates the conversation subscription.
 - Use `--follow` only when the user asks for live logs, and stop once enough evidence is captured. Do not leave a streaming command running indefinitely.
 
 3. Bound and minimize output:

package/plugin.yaml

@@ -1,26 +0,0 @@
-name: vercel
-display-name: Vercel
-description: Query Vercel deployments and logs with the Vercel CLI
-
-config-keys:
-  - project
-  - team
-
-capabilities:
-  - api
-
-env-vars:
-  JUNIOR_VERCEL_TOKEN:
-
-domains:
-  - api.vercel.com
-
-api-headers:
-  Authorization: Bearer ${JUNIOR_VERCEL_TOKEN}
-
-command-env:
-  VERCEL_TOKEN: host_managed_credential
-
-runtime-dependencies:
-  - type: npm
-    package: vercel