@cursor/july 0.1.94 → 0.1.96

package/templates/code-wiki/README.md

@@ -0,0 +1,34 @@
+# Code wiki
+
+Keeps `wiki/` pages current after a pull request merges. Opens a
+follow-up PR against that merge's base when a durable fact changed.
+Skips chores. Same-base updates stack on `wiki/<base>`.
+
+```bash
+npx @cursor/july init ./code-wiki --template code-wiki
+```
+
+`init` asks which repos to watch. Skip the prompt with
+`--var repos=owner/repo`.
+
+## Run
+
+Connect GitHub in Cursor for those repos. Then sign the host in:
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+Events and API calls use your Cursor GitHub connection. Replay a merged PR:
+
+```bash
+agent-sdk github replay https://github.com/owner/repo/pull/1 --dir . --action closed
+```
+
+## Files
+
+- `agent/lib/repos.ts`: watched repos
+- `agent/lib/wiki.ts`: wiki path rules
+- `agent/instructions.md`: what counts as a wiki update
+- `evals/wiki.eval.ts`: skip and update smoke cases

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

@@ -0,0 +1,8 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  tools: ["read", "grep"],
+  local: {
+    sandbox: true,
+  },
+});

package/templates/code-wiki/agent/channels/github.ts

@@ -0,0 +1,144 @@
+import type { HostGitHubClient } from "@cursor/july";
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+import { REPOS, watches } from "../lib/repos.js";
+import { WIKI_DIR, isWikiPath } from "../lib/wiki.js";
+
+const MAX_DIFF_CHARS = 150_000;
+const MAX_WIKI_PAGES = 40;
+const LIST_FILES_CAP = 3000;
+
+type Octokit = Awaited<ReturnType<HostGitHubClient["getOctokit"]>>;
+
+export default githubChannel({
+  cursorAccount: { repos: REPOS, permissions: "contents-write" },
+  deliverReplies: false,
+  onComment: () => null,
+  onPullRequest: async (ctx, pr) => {
+    if (!watches(ctx.repository.fullName)) {
+      return null;
+    }
+    if (pr.action !== "closed" || !pr.merged) {
+      return null;
+    }
+    if (pr.headRef.startsWith(`${WIKI_DIR}/`)) {
+      return null;
+    }
+    const octokit = await ctx.github.getOctokit();
+    const pull = {
+      owner: ctx.repository.owner,
+      repo: ctx.repository.name,
+      pull_number: pr.number,
+    };
+    const listed = await octokit.paginate(octokit.rest.pulls.listFiles, {
+      ...pull,
+      per_page: 100,
+    });
+    const files = listed.map((file) => file.filename);
+    if (
+      files.length > 0 &&
+      files.length < LIST_FILES_CAP &&
+      files.every(isWikiPath)
+    ) {
+      return null;
+    }
+    return {
+      auth: defaultGitHubAuth(ctx),
+      context: [
+        "This pull request merged. Read pr/files.txt, pr/diff.patch, and wiki/.",
+      ],
+      async workspaceFiles() {
+        const [diff, wiki] = await Promise.all([
+          octokit.rest.pulls.get({ ...pull, mediaType: { format: "diff" } }),
+          loadWiki(octokit, pull.owner, pull.repo, pr.baseRef),
+        ]);
+        const text = String(diff.data);
+        return {
+          "pr/base.ref": `${pr.baseRef}\n`,
+          "pr/files.txt": `${files.join("\n")}\n`,
+          "pr/diff.patch":
+            text.length > MAX_DIFF_CHARS
+              ? `${text.slice(0, MAX_DIFF_CHARS)}\n…[truncated]\n`
+              : text,
+          ...wiki,
+        };
+      },
+    };
+  },
+});
+
+async function loadWiki(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+  ref: string
+): Promise<Record<string, string>> {
+  const listed = await readContents(octokit, {
+    owner,
+    repo,
+    path: WIKI_DIR,
+    ref,
+  });
+  if (!Array.isArray(listed)) {
+    return { "wiki/pages.txt": "" };
+  }
+  const markdown = listed.filter(
+    (item) => item.type === "file" && item.name.endsWith(".md")
+  );
+  const truncated = markdown.length > MAX_WIKI_PAGES;
+  const files = markdown.slice(0, MAX_WIKI_PAGES);
+  const pages: Record<string, string> = {};
+  await Promise.all(
+    files.map(async (file) => {
+      const body = await readContents(octokit, {
+        owner,
+        repo,
+        path: `${WIKI_DIR}/${file.name}`,
+        ref,
+      });
+      if (
+        body === undefined ||
+        Array.isArray(body) ||
+        body.encoding !== "base64" ||
+        typeof body.content !== "string"
+      ) {
+        return;
+      }
+      pages[`${WIKI_DIR}/${file.name}`] = Buffer.from(
+        body.content,
+        "base64"
+      ).toString("utf8");
+    })
+  );
+  const names = Object.keys(pages).sort();
+  pages["wiki/pages.txt"] = truncated
+    ? `${names.join("\n")}\n…[truncated]\n`
+    : `${names.join("\n")}\n`;
+  return pages;
+}
+
+async function readContents(
+  octokit: Octokit,
+  args: { owner: string; repo: string; path: string; ref: string }
+) {
+  try {
+    const { data } = await octokit.rest.repos.getContent(args);
+    return data;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    error.status === 404
+  );
+}

package/templates/code-wiki/agent/instructions.md

@@ -0,0 +1,39 @@
+# Code wiki
+
+You keep the in-repo wiki current after a pull request merges.
+
+## Read
+
+The workspace has `pr/files.txt`, `pr/diff.patch`, and `wiki/`.
+`wiki/pages.txt` lists existing pages. Missing pages mean the wiki is
+empty. Read the file list and the pages that own the change. Use the
+diff only to test a fact.
+
+## Decide
+
+Update only when the merge changes a durable fact someone would look
+up later: how a system works, a public or operator contract, a default
+or ownership change, a removed feature.
+
+An empty wiki is not a license to document the whole repo. Create a
+page only for a durable contract in this merge.
+
+Skip lint, format, lockfiles, dependency pins, tests-only, cherry-picks,
+backports, telemetry-only changes, one-off bug fixes that leave the
+described behavior the same, knobs the wiki never mentioned, and facts
+the matching page already states.
+
+Do not write a changelog or a PR list.
+
+## Write
+
+Call `apply_wiki` once.
+
+- Skip: `{ verdict: "skip", reason }` with one line.
+- Update: `{ verdict: "update", reason, pages }` with full page bodies.
+
+Pages stay under `wiki/`, flat, `*.md`. Keep `_index.md` in sync when
+you add a page. Each catalog line names the page and the paths it owns.
+Short declarative sentences. Edit only the stale or missing facts.
+
+Reply with `skip` or `update` and the reason.

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

@@ -0,0 +1,5 @@
+export const REPOS: readonly string[] = ["owner/repo"];
+
+export function watches(fullName: string): boolean {
+  return REPOS.some((repo) => repo.toLowerCase() === fullName.toLowerCase());
+}

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/**/*"]
+}

package/templates/demo/agent/agent.ts

@@ -1,18 +1,8 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  },
   tools: ["read", "grep"],
   local: {
     sandbox: true,
-    cwd: join(homedir(), ".cache", "agent-serve", "demo"),
   },
 });