@cursor/july 0.1.96 → 0.1.99

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