@cursor/july 0.1.103 → 0.1.104

package/src/channels/github/progress.ts

@@ -28,6 +28,27 @@ export interface GitHubProgressPhaseCopy {
 export interface GitHubCommitStatusProgress extends GitHubProgressPhaseCopy {
   /** Check run name (unique per check in the merge box). */
   context: string;
+  /**
+   * Check Details URL for this session. When it resolves, it is written as
+   * `details_url` and (with {@link summaryLinkText}) appended to the summary.
+   */
+  detailsUrl?: (sessionId: string) => string | undefined;
+  /**
+   * `output.title` source. `"phase"` (default) uses the pending/success/
+   * failure copy. `"context"` uses the check name — the dashboard automation
+   * shape (`Cursor Security Agent: …`).
+   */
+  outputTitle?: "phase" | "context";
+  /**
+   * Markdown link label appended to the summary when {@link detailsUrl}
+   * resolves, e.g. `"View agent"`.
+   */
+  summaryLinkText?: string;
+  /**
+   * Conclusion for the failure phase. Default `"failure"`. Use `"neutral"`
+   * when a red merge-box check must not gate merge (findings live on the PR).
+   */
+  failureConclusion?: "failure" | "neutral";
 }
 
 export type GitHubBannerProgress = GitHubProgressPhaseCopy;
@@ -125,6 +146,7 @@ function progressLabel(
  */
 export async function applyGitHubProgress(input: {
   phase: GitHubProgressPhase;
+  sessionId?: string;
   channel: { state: GitHubChannelState };
   options: GitHubProgressOptions;
 }): Promise<void> {
@@ -139,6 +161,7 @@ export async function applyGitHubProgress(input: {
     tasks.push(
       postProgressCheckRun({
         phase: input.phase,
+        sessionId: input.sessionId,
         channel: input.channel,
         options: input.options,
         commitStatus,
@@ -159,8 +182,35 @@ export async function applyGitHubProgress(input: {
   await Promise.all(tasks);
 }
 
+function resolveProgressDetailsUrl(input: {
+  sessionId: string | undefined;
+  commitStatus: GitHubCommitStatusProgress;
+}): string | undefined {
+  if (
+    input.sessionId === undefined ||
+    input.commitStatus.detailsUrl === undefined
+  ) {
+    return undefined;
+  }
+  const url = input.commitStatus.detailsUrl(input.sessionId)?.trim();
+  return url === "" ? undefined : url;
+}
+
+function appendSummaryLink(
+  summary: string,
+  detailsUrl?: string,
+  linkText?: string
+): string {
+  const label = linkText?.trim();
+  if (detailsUrl === undefined || label === undefined || label === "") {
+    return summary;
+  }
+  return `${summary}\n\n[${label}](${detailsUrl})`;
+}
+
 async function postProgressCheckRun(input: {
   phase: GitHubProgressPhase;
+  sessionId?: string;
   channel: { state: GitHubChannelState };
   options: GitHubProgressOptions;
   commitStatus: GitHubCommitStatusProgress;
@@ -175,17 +225,32 @@ async function postProgressCheckRun(input: {
     return;
   }
   const sha = state.headSha;
-  const description = clipStatusDescription(
-    progressPhaseCopy({
-      copy: input.commitStatus,
-      phase: input.phase,
-      label: progressLabel(input.options, input.commitStatus.context),
-    })
+  const phaseCopy = progressPhaseCopy({
+    copy: input.commitStatus,
+    phase: input.phase,
+    label: progressLabel(input.options, input.commitStatus.context),
+  });
+  const title = clipStatusDescription(
+    input.commitStatus.outputTitle === "context"
+      ? input.commitStatus.context
+      : phaseCopy
   );
+  const detailsUrl = resolveProgressDetailsUrl({
+    sessionId: input.sessionId,
+    commitStatus: input.commitStatus,
+  });
   const write: GitHubCheckRunWriteInput = {
     name: input.commitStatus.context,
-    ...checkRunPhaseFields(input.phase),
-    output: { title: description, summary: description },
+    ...checkRunPhaseFields(input.phase, input.commitStatus.failureConclusion),
+    ...(detailsUrl === undefined ? {} : { detailsUrl }),
+    output: {
+      title,
+      summary: appendSummaryLink(
+        phaseCopy,
+        detailsUrl,
+        input.commitStatus.summaryLinkText
+      ),
+    },
   };
   const resource = {
     api: input.options.api,
@@ -249,14 +314,15 @@ function shouldRecreateCheckRun(
 }
 
 function checkRunPhaseFields(
-  phase: GitHubProgressPhase
+  phase: GitHubProgressPhase,
+  failureConclusion: "failure" | "neutral" = "failure"
 ): Pick<GitHubCheckRunWriteInput, "conclusion" | "status"> {
   if (phase === "pending") {
     return { status: "in_progress" };
   }
   return {
     status: "completed",
-    conclusion: phase === "success" ? "success" : "failure",
+    conclusion: phase === "success" ? "success" : failureConclusion,
   };
 }
 

package/src/channels/issues/index.ts

@@ -0,0 +1,9 @@
+export { issuesChannel } from "./issues-channel.js";
+export type {
+  IssueCreatedEvent,
+  IssueCreatedEventType,
+  IssueResource,
+  IssueState,
+  IssuesChannelOptions,
+} from "./types.js";
+export { ISSUE_CREATED_EVENT_TYPE } from "./types.js";

package/src/channels/issues/issues-channel.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { createFactoryResourceChannel } from "../../internal/factory-resource-channel.js";
+import type { ChannelDefinition } from "../../types.js";
+import {
+  ISSUE_CREATED_EVENT_TYPE,
+  type IssueCreatedEvent,
+  type IssuesChannelOptions,
+} from "./types.js";
+
+const issueResourceSchema = z
+  .object({
+    name: z.string().min(1),
+    title: z.string().min(1),
+    body: z.string().min(1),
+    state: z
+      .enum(["STATE_UNSPECIFIED", "STATE_OPEN", "STATE_CLOSED"])
+      .optional(),
+    createTime: z.string().min(1).optional(),
+    updateTime: z.string().min(1).optional(),
+    path: z.string().optional(),
+    etag: z.string().optional(),
+  })
+  .passthrough();
+
+const issueCreatedEventSchema: z.ZodType<IssueCreatedEvent> = z.object({
+  eventId: z.string().min(1),
+  eventType: z.literal(ISSUE_CREATED_EVENT_TYPE),
+  teamId: z.string().min(1),
+  occurredAtMs: z.number().int().nonnegative(),
+  issue: issueResourceSchema,
+});
+
+const pack = createFactoryResourceChannel({
+  kind: "issues",
+  eventTypes: [ISSUE_CREATED_EVENT_TYPE],
+  eventSchema: issueCreatedEventSchema,
+  replayDescription: "Replay a Factory issue-created event.",
+  invalidError: "invalid issue event",
+});
+
+export function issuesChannel(
+  options: IssuesChannelOptions
+): ChannelDefinition {
+  return pack.channel(options);
+}
+
+export function getIssuesChannelOptions(
+  definition: object
+): IssuesChannelOptions | undefined {
+  return pack.getOptions(definition);
+}

package/src/channels/issues/types.ts

@@ -0,0 +1,41 @@
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+
+export const ISSUE_CREATED_EVENT_TYPE = "issue.created" as const;
+
+export type IssueCreatedEventType = typeof ISSUE_CREATED_EVENT_TYPE;
+
+export type IssueState = "STATE_UNSPECIFIED" | "STATE_OPEN" | "STATE_CLOSED";
+
+/** Factory Issue JSON (camelCase proto JSON). */
+export type IssueResource = {
+  name: string;
+  title: string;
+  body: string;
+  state?: IssueState;
+  createTime?: string;
+  updateTime?: string;
+  path?: string;
+  etag?: string;
+};
+
+/** Factory `issue.created` for every Issue create. */
+export type IssueCreatedEvent = {
+  eventId: string;
+  eventType: IssueCreatedEventType;
+  teamId: string;
+  occurredAtMs: number;
+  issue: IssueResource;
+};
+
+export type IssuesChannelOptions = {
+  onEvent: (
+    event: IssueCreatedEvent,
+    args: ChannelHandlerArgs
+  ) => Promise<unknown> | unknown;
+  continuation?: ContinuationIdentity;
+  path?: string;
+  auth?: ChannelDefinition["auth"];
+  onStart?: ChannelDefinition["onStart"];
+  onStop?: ChannelDefinition["onStop"];
+};