@cursor/july 0.1.19 → 0.1.21

package/src/internal/discovery.builtin-tools.test.ts

@@ -0,0 +1,94 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import { defineTool } from "../tools.js";
+import type { AgentConfig } from "../types.js";
+import { loadAgentProject } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function scaffold(config: AgentConfig, authoredTools: string[] = []) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-builtin-disc-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "Be brief.\n");
+  for (const name of authoredTools) {
+    await mkdir(join(agentDir, "tools"), { recursive: true });
+    await writeFile(
+      join(agentDir, "tools", `${name}.ts`),
+      "export default {};\n"
+    );
+  }
+  return loadAgentProject(rootDir, {
+    importModule: async (path) => {
+      if (path.endsWith(join("agent", "agent.ts"))) {
+        return { default: defineAgent(config) };
+      }
+      return {
+        default: defineTool({
+          description: "Authored tool.",
+          execute: () => "authored",
+        }),
+      };
+    },
+  });
+}
+
+describe("loadAgentProject builtinTools", () => {
+  it("materializes reminder tools as server tools", async () => {
+    const project = await scaffold({ builtinTools: { reminders: true } });
+    const names = project.agent.tools.map((t) => t.name);
+    expect(names).toEqual([
+      "reminders_create",
+      "reminders_list",
+      "reminders_cancel",
+    ]);
+    expect(project.agent.tools.every((t) => t.execution === "server")).toBe(
+      true
+    );
+    expect(project.diagnostics).toEqual([]);
+  });
+
+  it("lets authored tools shadow built-ins, with a warning", async () => {
+    const project = await scaffold({ builtinTools: { reminders: true } }, [
+      "reminders_create",
+    ]);
+    const create = project.agent.tools.find(
+      (t) => t.name === "reminders_create"
+    );
+    expect(create?.description).toBe("Authored tool.");
+    expect(
+      project.agent.tools.filter((t) => t.name === "reminders_create")
+    ).toHaveLength(1);
+    expect(project.diagnostics).toEqual([
+      expect.objectContaining({
+        severity: "warning",
+        message: expect.stringContaining("shadows the built-in tool"),
+      }),
+    ]);
+  });
+
+  it("skips built-ins on cloud runtime, with a warning", async () => {
+    const project = await scaffold({
+      runtime: "cloud",
+      cloud: { repos: [{ url: "https://github.com/org/repo" }] },
+      builtinTools: { reminders: true },
+    });
+    expect(project.agent.tools).toEqual([]);
+    expect(
+      project.diagnostics.some((d) =>
+        d.message.includes("builtinTools are in-process server tools")
+      )
+    ).toBe(true);
+  });
+});

package/src/internal/discovery.concurrency.test.ts

@@ -0,0 +1,60 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import type { AgentConcurrencyOptions } from "../types.js";
+import { loadAgentProject, projectInfo } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function loadWithConcurrency(concurrency: AgentConcurrencyOptions) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-conc-disc-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "hi\n");
+  return loadAgentProject(rootDir, {
+    importModule: async () => ({
+      default: defineAgent({ model: "composer-2.5", concurrency }),
+    }),
+  });
+}
+
+describe("loadAgentProject concurrency", () => {
+  it("resolves the concurrency block and surfaces it in projectInfo", async () => {
+    const project = await loadWithConcurrency({ maxRunningTurns: 3 });
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.concurrency).toEqual({ maxRunningTurns: 3 });
+    expect(projectInfo(project).concurrency).toEqual({ maxRunningTurns: 3 });
+  });
+
+  it("rejects a non-positive maxRunningTurns with an error diagnostic", async () => {
+    const project = await loadWithConcurrency({ maxRunningTurns: 0 });
+    expect(project.agent.concurrency).toBeUndefined();
+    expect(
+      project.diagnostics.some(
+        (d) =>
+          d.severity === "error" &&
+          d.message.includes("concurrency.maxRunningTurns")
+      )
+    ).toBe(true);
+  });
+
+  it("rejects a maxRunningTurns above the hard limit", async () => {
+    const project = await loadWithConcurrency({ maxRunningTurns: 10_000 });
+    expect(project.agent.concurrency).toBeUndefined();
+    expect(
+      project.diagnostics.some(
+        (d) => d.severity === "error" && d.message.includes("hard limit")
+      )
+    ).toBe(true);
+  });
+});

package/src/internal/discovery.cursor-account.test.ts

@@ -0,0 +1,133 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineConnection } from "../connections.js";
+import { defineAgent } from "../index.js";
+import { loadAgentProject } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function loadWithCursorAccountConnection(
+  connectionSource: string
+): Promise<Awaited<ReturnType<typeof loadAgentProject>>> {
+  const rootDir = await mkdtemp(
+    join(tmpdir(), "agent-serve-cursor-account-disc-")
+  );
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  const connectionsDir = join(agentDir, "mcp-connections");
+  await mkdir(connectionsDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "hi\n");
+  await writeFile(join(connectionsDir, "cursor.ts"), connectionSource);
+  return loadAgentProject(rootDir, {
+    importModule: async (absolutePath) => {
+      if (absolutePath.endsWith(`${join("mcp-connections", "cursor.ts")}`)) {
+        // Evaluate the authored source shape without a full TS transpile.
+        if (connectionSource.includes('servers: ["*", "Linear"]')) {
+          return {
+            default: defineConnection({
+              cursorAccount: true,
+              servers: ["*", "Linear"],
+            }),
+          };
+        }
+        if (connectionSource.includes('servers: "*"')) {
+          return {
+            default: defineConnection({
+              cursorAccount: true,
+              servers: "*",
+            }),
+          };
+        }
+        if (connectionSource.includes('servers: ["*"]')) {
+          return {
+            default: defineConnection({
+              cursorAccount: true,
+              servers: ["*"],
+            }),
+          };
+        }
+        if (connectionSource.includes("servers: []")) {
+          return {
+            default: defineConnection({
+              cursorAccount: true,
+              servers: [],
+            }),
+          };
+        }
+        return {
+          default: defineConnection({ cursorAccount: true }),
+        };
+      }
+      return { default: defineAgent({ model: "composer-2.5" }) };
+    },
+  });
+}
+
+describe("loadAgentProject cursorAccount servers", () => {
+  it("omits servers when forwarding every account connector", async () => {
+    const project = await loadWithCursorAccountConnection(
+      `export default { cursorAccount: true };\n`
+    );
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.connections).toEqual([
+      { name: "cursor", transport: { cursorAccount: true } },
+    ]);
+  });
+
+  it('normalizes servers: "*" to every connected server', async () => {
+    const project = await loadWithCursorAccountConnection(
+      `export default { cursorAccount: true, servers: "*" };\n`
+    );
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.connections[0]?.transport).toEqual({
+      cursorAccount: true,
+    });
+  });
+
+  it('normalizes servers: ["*"] to every connected server', async () => {
+    const project = await loadWithCursorAccountConnection(
+      `export default { cursorAccount: true, servers: ["*"] };\n`
+    );
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.connections[0]?.transport).toEqual({
+      cursorAccount: true,
+    });
+  });
+
+  it("rejects an empty servers allowlist", async () => {
+    const project = await loadWithCursorAccountConnection(
+      `export default { cursorAccount: true, servers: [] };\n`
+    );
+    expect(project.agent.connections).toEqual([]);
+    expect(
+      project.diagnostics.some(
+        (d) =>
+          d.severity === "error" &&
+          d.message.includes("non-empty list of connector names")
+      )
+    ).toBe(true);
+  });
+
+  it('rejects mixing "*" with concrete connector names', async () => {
+    const project = await loadWithCursorAccountConnection(
+      `export default { cursorAccount: true, servers: ["*", "Linear"] };\n`
+    );
+    expect(project.agent.connections).toEqual([]);
+    expect(
+      project.diagnostics.some(
+        (d) =>
+          d.severity === "error" &&
+          d.message.includes('cannot mix `"*"` with connector names')
+      )
+    ).toBe(true);
+  });
+});

package/src/internal/discovery.cwd.test.ts

@@ -0,0 +1,83 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import { loadAgentProject } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+describe("loadAgentProject cwd", () => {
+  it("resolves relative cwd against the project root and keeps absolute cwd", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-cwd-disc-"));
+    cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+    const agentDir = join(rootDir, "agent");
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+    await writeFile(join(agentDir, "instructions.md"), "hi\n");
+
+    const relative = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          model: "composer-2.5",
+          local: { cwd: "./harness-out" },
+        }),
+      }),
+    });
+    expect(relative.agent.local?.cwd).toBe(join(rootDir, "harness-out"));
+
+    const absolutePath = join(tmpdir(), "agent-serve-abs-cwd");
+    const absolute = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          model: "composer-2.5",
+          local: { cwd: absolutePath },
+        }),
+      }),
+    });
+    expect(absolute.agent.local?.cwd).toBe(absolutePath);
+  });
+
+  it("resolves workspaceDir the same way and warns when cwd is also set", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-ws-disc-"));
+    cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+    const agentDir = join(rootDir, "agent");
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+    await writeFile(join(agentDir, "instructions.md"), "hi\n");
+
+    const pinned = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          model: "composer-2.5",
+          local: { workspaceDir: "./checkout" },
+        }),
+      }),
+    });
+    expect(pinned.agent.local?.workspaceDir).toBe(join(rootDir, "checkout"));
+    expect(pinned.agent.local?.cwd).toBeUndefined();
+    expect(pinned.diagnostics).toEqual([]);
+
+    const both = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          model: "composer-2.5",
+          local: { cwd: "./harness-out", workspaceDir: "./checkout" },
+        }),
+      }),
+    });
+    expect(both.agent.local?.workspaceDir).toBe(join(rootDir, "checkout"));
+    expect(both.diagnostics).toContainEqual(
+      expect.objectContaining({
+        severity: "warning",
+        message: expect.stringContaining("local.cwd is unused"),
+      })
+    );
+  });
+});

package/src/internal/discovery.hosting.test.ts

@@ -0,0 +1,80 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import type { AgentHostingOptions } from "../types.js";
+import { loadAgentProject, projectInfo } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function loadWithHosting(hosting: AgentHostingOptions) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-hosting-disc-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "hi\n");
+  return loadAgentProject(rootDir, {
+    importModule: async () => ({
+      default: defineAgent({ model: "composer-2.5", hosting }),
+    }),
+  });
+}
+
+describe("loadAgentProject hosting", () => {
+  it("resolves the hosting block and surfaces it in projectInfo", async () => {
+    const project = await loadWithHosting({
+      egressDomains: ["api.example.com", "*.internal.example.com"],
+      secretNames: ["OPENAI_API_KEY"],
+    });
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.hosting).toEqual({
+      egressDomains: ["api.example.com", "*.internal.example.com"],
+      secretNames: ["OPENAI_API_KEY"],
+    });
+    expect(projectInfo(project).hosting).toEqual(project.agent.hosting);
+  });
+
+  it("emits warning diagnostics (not errors) for grammar violations", async () => {
+    const project = await loadWithHosting({
+      // Uppercase, single-label, numeric TLD, double wildcard: all invalid.
+      egressDomains: ["API.example.com", "localhost", "a.b.123", "*.*.x.com"],
+      secretNames: ["lower_case", "CURSOR_API_KEY", "A".repeat(65)],
+    });
+    const warnings = project.diagnostics.filter(
+      (d) => d.severity === "warning"
+    );
+    expect(project.diagnostics).toHaveLength(warnings.length);
+    const messages = warnings.map((d) => d.message).join("\n");
+    expect(messages).toContain('Invalid egress domain "API.example.com"');
+    expect(messages).toContain('Invalid egress domain "localhost"');
+    expect(messages).toContain('Invalid egress domain "a.b.123"');
+    expect(messages).toContain('Invalid egress domain "*.*.x.com"');
+    expect(messages).toContain('Invalid secret name "lower_case"');
+    expect(messages).toContain("platform-managed");
+    expect(messages).toContain("too long");
+    // Invalid entries are still kept — the backend stays authoritative.
+    expect(project.agent.hosting?.egressDomains).toHaveLength(4);
+  });
+
+  it("warns when egressDomains exceeds the deploy cap", async () => {
+    const project = await loadWithHosting({
+      egressDomains: Array.from(
+        { length: 21 },
+        (_, i) => `svc${i}.example.com`
+      ),
+    });
+    expect(
+      project.diagnostics.some(
+        (d) => d.severity === "warning" && d.message.includes("capped at 20")
+      )
+    ).toBe(true);
+  });
+});

package/src/internal/discovery.identity.test.ts

@@ -0,0 +1,44 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import { loadAgentProject } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+describe("loadAgentProject identity preamble", () => {
+  it("prepends the resolved name into instructions", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-identity-"));
+    cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+    const agentDir = join(rootDir, "agent");
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+    await writeFile(
+      join(agentDir, "instructions.md"),
+      "Be brief and specific.\n"
+    );
+
+    const project = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          name: "Benny",
+          model: "composer-2.5",
+        }),
+      }),
+    });
+
+    expect(project.agent.instructions).toBe(
+      [
+        "You are Benny. That is your name; use it when people ask who you are.",
+        "Be brief and specific.",
+      ].join("\n\n")
+    );
+  });
+});

package/src/internal/docs-site.test.ts

@@ -0,0 +1,66 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeAll, describe, expect, it } from "vitest";
+import { resolveDocsFile } from "./docs-site.js";
+
+describe("resolveDocsFile", () => {
+  let dist: string;
+
+  beforeAll(async () => {
+    dist = await mkdtemp(join(tmpdir(), "agent-serve-docs-"));
+    await mkdir(join(dist, "guides"), { recursive: true });
+    await mkdir(join(dist, "assets", "chunks"), { recursive: true });
+    await writeFile(join(dist, "index.html"), "<html>index</html>");
+    await writeFile(join(dist, "quickstart.html"), "<html>quickstart</html>");
+    await writeFile(join(dist, "guides", "slack.html"), "<html>slack</html>");
+    await writeFile(join(dist, "assets", "chunks", "app.js"), "js");
+    await writeFile(join(dist, "hashmap.json"), "{}");
+  });
+
+  it("serves the site index for the empty path", () => {
+    expect(resolveDocsFile("", dist)).toBe(join(dist, "index.html"));
+    expect(resolveDocsFile("/", dist)).toBe(join(dist, "index.html"));
+  });
+
+  it("resolves clean page URLs through the .html chain", () => {
+    expect(resolveDocsFile("quickstart", dist)).toBe(
+      join(dist, "quickstart.html")
+    );
+    expect(resolveDocsFile("guides/slack", dist)).toBe(
+      join(dist, "guides", "slack.html")
+    );
+    expect(resolveDocsFile("guides/slack/", dist)).toBe(
+      join(dist, "guides", "slack.html")
+    );
+  });
+
+  it("serves exact files (assets, json, explicit .html)", () => {
+    expect(resolveDocsFile("assets/chunks/app.js", dist)).toBe(
+      join(dist, "assets", "chunks", "app.js")
+    );
+    expect(resolveDocsFile("hashmap.json", dist)).toBe(
+      join(dist, "hashmap.json")
+    );
+    expect(resolveDocsFile("quickstart.html", dist)).toBe(
+      join(dist, "quickstart.html")
+    );
+  });
+
+  it("returns undefined for unknown pages", () => {
+    expect(resolveDocsFile("nope", dist)).toBeUndefined();
+    expect(resolveDocsFile("guides/nope", dist)).toBeUndefined();
+  });
+
+  it("rejects traversal out of the dist dir", () => {
+    expect(resolveDocsFile("../package.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("..%2Fpackage.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("guides/../../package.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("..", dist)).toBeUndefined();
+  });
+
+  it("does not treat directories as files", () => {
+    // `guides` has no guides.html and no guides/index.html.
+    expect(resolveDocsFile("guides", dist)).toBeUndefined();
+  });
+});

package/src/internal/duration.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { isValidDuration, parseDuration } from "./duration.js";
+
+describe("parseDuration", () => {
+  it("parses short units", () => {
+    expect(parseDuration("30s")).toBe(30_000);
+    expect(parseDuration("5m")).toBe(5 * 60_000);
+    expect(parseDuration("2h")).toBe(2 * 3_600_000);
+    expect(parseDuration("1d")).toBe(86_400_000);
+  });
+
+  it("parses word units", () => {
+    expect(parseDuration("10 minutes")).toBe(10 * 60_000);
+    expect(parseDuration("1.5h")).toBe(90 * 60_000);
+  });
+
+  it("accepts bare numbers as milliseconds", () => {
+    expect(parseDuration(1500)).toBe(1500);
+    expect(parseDuration("1500")).toBe(1500);
+  });
+
+  it("rejects invalid input", () => {
+    expect(() => parseDuration("")).toThrow();
+    expect(() => parseDuration("abc")).toThrow();
+    expect(() => parseDuration("5x")).toThrow();
+    expect(isValidDuration("5m")).toBe(true);
+    expect(isValidDuration("nope")).toBe(false);
+  });
+});