@cursor/july 0.1.95 → 0.1.96

package/templates/code-wiki/agent/lib/wiki.ts

@@ -0,0 +1,22 @@
+export const WIKI_DIR = "wiki";
+
+const PAGE = /^[A-Za-z0-9._-]+\.md$/;
+
+export function isWikiPath(path: string): boolean {
+  return path === WIKI_DIR || path.startsWith(`${WIKI_DIR}/`);
+}
+
+export function wikiPagePath(raw: string): string | undefined {
+  const path = raw.replace(/^\/+/, "");
+  if (path.includes("..") || path.includes("\\")) {
+    return undefined;
+  }
+  if (!path.startsWith(`${WIKI_DIR}/`) || !path.endsWith(".md")) {
+    return undefined;
+  }
+  const name = path.slice(WIKI_DIR.length + 1);
+  if (!PAGE.test(name)) {
+    return undefined;
+  }
+  return `${WIKI_DIR}/${name}`;
+}

package/templates/code-wiki/agent/tools/apply_wiki.ts

@@ -0,0 +1,219 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { HostGitHubClient } from "@cursor/july";
+import { parseGitHubPrContinuationKey } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+import { wikiPagePath } from "../lib/wiki.js";
+
+const page = z.object({
+  path: z.string().min(1).max(160),
+  content: z.string().min(1).max(32_000),
+});
+
+type Page = z.infer<typeof page>;
+type Octokit = Awaited<ReturnType<HostGitHubClient["getOctokit"]>>;
+
+type Write = {
+  octokit: Octokit;
+  owner: string;
+  repo: string;
+  number: number;
+  label: string;
+  reason: string;
+  pages: Page[];
+  base: string;
+  branch: string;
+};
+
+export default defineTool({
+  description:
+    "Skip or open a wiki follow-up PR for this merged pull request. Call once.",
+  inputSchema: z.discriminatedUnion("verdict", [
+    z.object({
+      verdict: z.literal("skip"),
+      reason: z.string().min(1).max(280),
+    }),
+    z.object({
+      verdict: z.literal("update"),
+      reason: z.string().min(1).max(280),
+      pages: z.array(page).min(1).max(8),
+    }),
+  ]),
+  async execute(input, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval", verdict: input.verdict };
+    }
+    if (input.verdict === "skip") {
+      return { posted: false, reason: input.reason, verdict: "skip" };
+    }
+    const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? "");
+    if (ref === undefined) {
+      throw new Error("apply_wiki requires a GitHub pull request session");
+    }
+    const base = (
+      await readFile(join(ctx.workspaceDir, "pr/base.ref"), "utf8")
+    ).trim();
+    const branch = wikiUpdateBranch(base);
+    if (branch === undefined) {
+      throw new Error("missing pr/base.ref");
+    }
+    const pages = input.pages.map((item) => {
+      const path = wikiPagePath(item.path);
+      if (path === undefined) {
+        throw new Error(`invalid wiki path: ${item.path}`);
+      }
+      return { path, content: item.content };
+    });
+    return openWikiPr({
+      octokit: await ctx.host.github.getOctokit(),
+      owner: ref.owner,
+      repo: ref.repo,
+      number: ref.number,
+      label: `${ref.owner}/${ref.repo}#${ref.number}`,
+      reason: input.reason,
+      pages,
+      base,
+      branch,
+    });
+  },
+});
+
+function wikiUpdateBranch(base: string): string | undefined {
+  if (base === "" || !/^[A-Za-z0-9._/-]+$/.test(base)) {
+    return undefined;
+  }
+  return `wiki/${base.replaceAll("/", "-")}`;
+}
+
+async function openWikiPr(input: Write) {
+  const repo = { owner: input.owner, repo: input.repo };
+  const existing = await input.octokit.rest.pulls.list({
+    ...repo,
+    state: "open",
+    head: `${input.owner}:${input.branch}`,
+    base: input.base,
+    per_page: 1,
+  });
+  const open = existing.data[0];
+  if (open !== undefined && citesSource(open.body, input.number)) {
+    return {
+      posted: false,
+      reason: "exists",
+      verdict: "update",
+      pr: input.label,
+      url: open.html_url,
+    };
+  }
+  const branchSha = await refSha(input.octokit, repo, input.branch);
+  const parent =
+    branchSha ?? (await refSha(input.octokit, repo, input.base));
+  if (parent === undefined) {
+    throw new Error(`missing base ref: ${input.base}`);
+  }
+  const { data: commit } = await input.octokit.rest.git.getCommit({
+    ...repo,
+    commit_sha: parent,
+  });
+  const blobs = await Promise.all(
+    input.pages.map(async (item) => {
+      const { data } = await input.octokit.rest.git.createBlob({
+        ...repo,
+        content: Buffer.from(item.content).toString("base64"),
+        encoding: "base64",
+      });
+      return {
+        path: item.path,
+        mode: "100644" as const,
+        type: "blob" as const,
+        sha: data.sha,
+      };
+    })
+  );
+  const { data: tree } = await input.octokit.rest.git.createTree({
+    ...repo,
+    base_tree: commit.tree.sha,
+    tree: blobs,
+  });
+  const { data: next } = await input.octokit.rest.git.createCommit({
+    ...repo,
+    message: `wiki: ${input.reason}`,
+    tree: tree.sha,
+    parents: [parent],
+  });
+  if (branchSha === undefined) {
+    await input.octokit.rest.git.createRef({
+      ...repo,
+      ref: `refs/heads/${input.branch}`,
+      sha: next.sha,
+    });
+  } else {
+    await input.octokit.rest.git.updateRef({
+      ...repo,
+      ref: `heads/${input.branch}`,
+      sha: next.sha,
+    });
+  }
+  if (open !== undefined) {
+    await input.octokit.rest.pulls.update({
+      ...repo,
+      pull_number: open.number,
+      body: appendSource(open.body ?? "", input.reason, input.number),
+    });
+    return {
+      posted: true,
+      verdict: "update",
+      pr: input.label,
+      url: open.html_url,
+    };
+  }
+  const { data: pull } = await input.octokit.rest.pulls.create({
+    ...repo,
+    title: `wiki: update from #${input.number}`,
+    head: input.branch,
+    base: input.base,
+    body: `${input.reason}\n\nSource: #${input.number}`,
+  });
+  return {
+    posted: true,
+    verdict: "update",
+    pr: input.label,
+    url: pull.html_url,
+  };
+}
+
+async function refSha(
+  octokit: Octokit,
+  repo: { owner: string; repo: string },
+  name: string
+): Promise<string | undefined> {
+  try {
+    const { data } = await octokit.rest.git.getRef({
+      ...repo,
+      ref: `heads/${name}`,
+    });
+    return data.object.sha;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function citesSource(body: string | null | undefined, number: number): boolean {
+  return new RegExp(`(?:^|\\n)Source:.*#${number}(?:\\s|$)`).test(body ?? "");
+}
+
+function appendSource(body: string, reason: string, number: number): string {
+  return `${body.trim()}\n\n${reason}\nSource: #${number}`;
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    error.status === 404
+  );
+}

package/templates/code-wiki/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/code-wiki/evals/wiki.eval.ts

@@ -0,0 +1,132 @@
+import { defineEval } from "@cursor/july/evals";
+
+function merged(title: string): string {
+  return [
+    "GitHub pull request trigger: acme/api#12",
+    "Action: closed",
+    "PR: https://github.com/acme/api/pull/12",
+    `Title: ${title}`,
+    "Head: feat/change (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa)",
+    "Base: main",
+    "Author: sam",
+    "",
+    "This pull request merged. Read pr/files.txt, pr/diff.patch, and wiki/.",
+  ].join("\n");
+}
+
+const INDEX = [
+  "# Wiki",
+  "",
+  "- [Billing](billing.md): usage events posted to the warehouse",
+  "- [App](app.md): HTTP handlers and UI chrome",
+  "",
+].join("\n");
+
+const BILLING = [
+  "# Billing",
+  "",
+  "Usage events are protobuf messages in `proto/billing.proto`.",
+  "Each event has `account_id` and `amount_cents`.",
+  "",
+].join("\n");
+
+const APP = [
+  "# App",
+  "",
+  "The sidebar opener is a querySelector on `.opener`.",
+  "",
+].join("\n");
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "skip-lint",
+      description: "A quote-style lint fix does not open a wiki PR.",
+      async test(t) {
+        await t.send(merged("Fix sidebar opener lint failure"), {
+          workspaceFiles: {
+            "pr/files.txt": "src/sidebar.ts\n",
+            "pr/diff.patch": [
+              "diff --git a/src/sidebar.ts b/src/sidebar.ts",
+              "-const opener = document.querySelector('.opener')",
+              '+const opener = document.querySelector(".opener");',
+            ].join("\n"),
+            "wiki/pages.txt": "wiki/_index.md\nwiki/app.md\n",
+            "wiki/_index.md": INDEX,
+            "wiki/app.md": APP,
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_wiki", { input: { verdict: "skip" } });
+      },
+    },
+    {
+      id: "update-contract",
+      description: "New billing proto fields update the billing page.",
+      async test(t) {
+        await t.send(merged("Add unified fields to billing events"), {
+          workspaceFiles: {
+            "pr/files.txt": "proto/billing.proto\n",
+            "pr/diff.patch": [
+              "diff --git a/proto/billing.proto b/proto/billing.proto",
+              " message UsageEvent {",
+              "   string account_id = 1;",
+              "   int64 amount_cents = 2;",
+              "+  string usage_unit = 12;",
+              "+  string workspace_id = 13;",
+              " }",
+            ].join("\n"),
+            "wiki/pages.txt": "wiki/_index.md\nwiki/billing.md\n",
+            "wiki/_index.md": INDEX,
+            "wiki/billing.md": BILLING,
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_wiki", { input: { verdict: "update" } });
+      },
+    },
+    {
+      id: "skip-docs",
+      description: "A markdown-only merge does not open a wiki PR.",
+      async test(t) {
+        await t.send(merged("Document factory delete in servicetests"), {
+          workspaceFiles: {
+            "pr/files.txt": "backend/server/src/factory/README.md\n",
+            "pr/diff.patch": [
+              "diff --git a/backend/server/src/factory/README.md b/backend/server/src/factory/README.md",
+              "+Drive environment delete from markdown servicetests.",
+            ].join("\n"),
+            "wiki/pages.txt": "wiki/_index.md\n",
+            "wiki/_index.md": INDEX,
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_wiki", { input: { verdict: "skip" } });
+      },
+    },
+    {
+      id: "skip-cherry-pick",
+      description: "A release-train cherry-pick does not open a wiki PR.",
+      async test(t) {
+        await t.send(
+          merged("[CP releases/3.19] Stop stale Project corner loaders"),
+          {
+            workspaceFiles: {
+              "pr/files.txt": "src/projects.ts\n",
+              "pr/diff.patch": [
+                "diff --git a/src/projects.ts b/src/projects.ts",
+                "+if (status.seq < last.seq) return;",
+              ].join("\n"),
+              "wiki/pages.txt": "wiki/_index.md\nwiki/app.md\n",
+              "wiki/_index.md": INDEX,
+              "wiki/app.md": APP,
+            },
+          }
+        );
+        t.succeeded();
+        t.calledTool("apply_wiki", { input: { verdict: "skip" } });
+      },
+    },
+  ],
+});

package/templates/code-wiki/init.json

@@ -0,0 +1,25 @@
+{
+  "questions": [
+    {
+      "id": "repos",
+      "prompt": "Which GitHub repos should this agent watch for merges?",
+      "hint": "Comma-separated owner/repo. One GitHub owner.",
+      "placeholder": "acme/api, acme/web",
+      "parse": "owner-repo-list"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/lib/repos.ts",
+      "find": "[\"owner/repo\"]",
+      "answer": "repos",
+      "as": "json-array"
+    },
+    {
+      "file": "README.md",
+      "find": "owner/repo",
+      "answer": "repos",
+      "as": "first"
+    }
+  ]
+}

package/templates/code-wiki/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "code-wiki",
+  "private": true,
+  "type": "module",
+  "description": "Keeps an in-repo wiki current after pull requests merge.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/code-wiki/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}