@cursor/july 0.1.95 → 0.1.97

package/templates/agents-md/agent/tools/apply_agents.ts

@@ -0,0 +1,226 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { HostGitHubClient } from "@cursor/july";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+import { agentsPath, parseRepo, updateBranch } from "../lib/paths.js";
+
+const file = z.object({
+  path: z.string().min(1).max(240),
+  content: z.string().min(1).max(64_000),
+});
+
+type File = z.infer<typeof file>;
+type Octokit = Awaited<ReturnType<HostGitHubClient["getOctokit"]>>;
+
+type Write = {
+  octokit: Octokit;
+  owner: string;
+  repo: string;
+  window: string;
+  reason: string;
+  files: File[];
+  base: string;
+  branch: string;
+};
+
+export default defineTool({
+  description:
+    "Skip or open an AGENTS.md follow-up PR for this weekly review. Call once.",
+  needsApproval: (input) => input.verdict === "update",
+  effect: (input) => (input.verdict === "update" ? "write" : "read"),
+  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),
+      files: z.array(file).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 dir = ctx.workspaceDir;
+    const repo = parseRepo(await readTrimmed(dir, "week/repo.txt"));
+    const base = await readTrimmed(dir, "week/base.ref");
+    const window = await readTrimmed(dir, "week/window.txt");
+    const branch = updateBranch(base);
+    if (repo === undefined || branch === undefined || window === "") {
+      throw new Error("missing week/repo.txt, week/base.ref, or week/window.txt");
+    }
+    const files = input.files.map((item) => {
+      const path = agentsPath(item.path);
+      if (path === undefined) {
+        throw new Error(`invalid AGENTS.md path: ${item.path}`);
+      }
+      return { path, content: item.content };
+    });
+    return openAgentsPr({
+      octokit: await ctx.host.github.getOctokit(),
+      owner: repo.owner,
+      repo: repo.repo,
+      window,
+      reason: input.reason,
+      files,
+      base,
+      branch,
+    });
+  },
+});
+
+async function openAgentsPr(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 && citesWindow(open.body, input.window)) {
+    return {
+      posted: false,
+      reason: "exists",
+      verdict: "update",
+      window: input.window,
+      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.files.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: `agents.md: ${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: appendWindow(open.body ?? "", input.reason, input.window),
+    });
+    return {
+      posted: true,
+      verdict: "update",
+      window: input.window,
+      url: open.html_url,
+    };
+  }
+  const { data: pull } = await input.octokit.rest.pulls.create({
+    ...repo,
+    title: `agents.md: update for ${input.window}`,
+    head: input.branch,
+    base: input.base,
+    draft: true,
+    body: pullBody(input.reason, input.window),
+  });
+  return {
+    posted: true,
+    verdict: "update",
+    window: input.window,
+    url: pull.html_url,
+  };
+}
+
+async function readTrimmed(dir: string, rel: string): Promise<string> {
+  return (await readFile(join(dir, rel), "utf8")).trim();
+}
+
+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 pullBody(reason: string, window: string): string {
+  return `${reason}
+
+Window: ${window}
+
+This pull request rewrites AGENTS.md. Those files are always-applied agent instructions. Review the bodies, then mark the draft ready and merge.`;
+}
+
+function citesWindow(body: string | null | undefined, window: string): boolean {
+  return new RegExp(
+    `(?:^|\\n)Window: ${escapeRegExp(window)}(?:\\s|$)`
+  ).test(body ?? "");
+}
+
+function appendWindow(body: string, reason: string, window: string): string {
+  return `${body.trim()}\n\n${reason}\nWindow: ${window}`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    error.status === 404
+  );
+}

package/templates/agents-md/evals/agents.eval.ts

@@ -0,0 +1,135 @@
+import { defineEval } from "@cursor/july/evals";
+
+const WINDOW = "2026-08-26/2026-09-02";
+
+function weekly(): string {
+  return [
+    `Weekly AGENTS.md review for acme/api (${WINDOW}).`,
+    "Read week/ and week/tree/. Call apply_agents once.",
+  ].join("\n");
+}
+
+const AGENTS = [
+  "# API",
+  "",
+  "Usage events are protobuf messages in `proto/billing.proto`.",
+  "Do not add ad-hoc billing columns on the request path.",
+  "",
+].join("\n");
+
+const CHORE = [
+  "# Merged pull requests",
+  "",
+  "## #12 Fix sidebar opener lint failure",
+  "url: https://github.com/acme/api/pull/12",
+  "author: @sam",
+  "merged: 2026-08-28T16:00:00Z",
+  "files: src/sidebar.ts",
+  "",
+  "Quote style only.",
+  "",
+].join("\n");
+
+const RULE = [
+  "# Merged pull requests",
+  "",
+  "## #18 Route every billing write through UsageEvent",
+  "url: https://github.com/acme/api/pull/18",
+  "author: @sam",
+  "merged: 2026-08-29T18:00:00Z",
+  "files: proto/billing.proto, src/billing.ts",
+  "",
+  "Adds usage_unit and workspace_id to UsageEvent.",
+  "",
+  "### comments",
+  "- @lee: always put new billing fields on UsageEvent. no request-path columns.",
+  "",
+].join("\n");
+
+const SLACK = [
+  "## #eng-api",
+  "- <@U1>: lunch at 12",
+  "- <@U2>: yes, every new billing field goes on UsageEvent from now on",
+  "",
+].join("\n");
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "skip-chore",
+      description: "A lint-only week does not open an AGENTS.md PR.",
+      async test(t) {
+        await t.send(weekly(), {
+          workspaceFiles: {
+            "week/window.txt": `${WINDOW}\n`,
+            "week/repo.txt": "acme/api\n",
+            "week/base.ref": "main\n",
+            "week/files.txt": "AGENTS.md\n",
+            "week/prs.md": CHORE,
+            "week/slack.md": "## #eng-api\n- <@U1>: lunch at 12\n",
+            "week/tree/AGENTS.md.txt": AGENTS,
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_agents", { input: { verdict: "skip" } });
+      },
+    },
+    {
+      id: "update-rule",
+      description: "A repeated billing rule parks the AGENTS.md write.",
+      async test(t) {
+        await t.send(weekly(), {
+          workspaceFiles: {
+            "week/window.txt": `${WINDOW}\n`,
+            "week/repo.txt": "acme/api\n",
+            "week/base.ref": "main\n",
+            "week/files.txt": "AGENTS.md\n",
+            "week/prs.md": RULE,
+            "week/slack.md": SLACK,
+            "week/tree/AGENTS.md.txt": "# API\n\nKeep handlers thin.\n",
+          },
+        });
+        t.parked();
+        t.calledTool("apply_agents", { input: { verdict: "update" } });
+      },
+    },
+    {
+      id: "skip-known",
+      description: "A rule already in AGENTS.md stays quiet.",
+      async test(t) {
+        await t.send(weekly(), {
+          workspaceFiles: {
+            "week/window.txt": `${WINDOW}\n`,
+            "week/repo.txt": "acme/api\n",
+            "week/base.ref": "main\n",
+            "week/files.txt": "AGENTS.md\n",
+            "week/prs.md": RULE,
+            "week/slack.md": SLACK,
+            "week/tree/AGENTS.md.txt": AGENTS,
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_agents", { input: { verdict: "skip" } });
+      },
+    },
+    {
+      id: "skip-empty",
+      description: "An empty week does not open an AGENTS.md PR.",
+      async test(t) {
+        await t.send(weekly(), {
+          workspaceFiles: {
+            "week/window.txt": `${WINDOW}\n`,
+            "week/repo.txt": "acme/api\n",
+            "week/base.ref": "main\n",
+            "week/files.txt": "\n",
+            "week/prs.md": "No merged pull requests this week.\n",
+            "week/slack.md": "No Slack channels configured.\n",
+          },
+        });
+        t.succeeded();
+        t.calledTool("apply_agents", { input: { verdict: "skip" } });
+      },
+    },
+  ],
+});

package/templates/agents-md/evals/evals.config.ts

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

package/templates/agents-md/init.json

@@ -0,0 +1,38 @@
+{
+  "questions": [
+    {
+      "id": "repos",
+      "prompt": "Which GitHub repo should this agent maintain AGENTS.md for?",
+      "hint": "One owner/repo. Init once per app.",
+      "placeholder": "acme/api",
+      "parse": "owner-repo-list"
+    },
+    {
+      "id": "slack",
+      "prompt": "Which Slack channels should this agent read?",
+      "hint": "Comma-separated #names or channel ids. Invite the bot, including to private channels. Use none to skip Slack.",
+      "placeholder": "#eng-api, #api-private",
+      "default": "none"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/lib/config.ts",
+      "find": "[\"owner/repo\"]",
+      "answer": "repos",
+      "as": "json-array"
+    },
+    {
+      "file": "agent/lib/config.ts",
+      "find": "[\"#eng\"]",
+      "answer": "slack",
+      "as": "json-array"
+    },
+    {
+      "file": "README.md",
+      "find": "owner/repo",
+      "answer": "repos",
+      "as": "first"
+    }
+  ]
+}

package/templates/agents-md/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "agents-md",
+  "private": true,
+  "type": "module",
+  "description": "Keeps AGENTS.md current from last week's merged PRs and Slack.",
+  "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/agents-md/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/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}`;
+}