@cursor/july 0.1.68 → 0.1.74

package/src/internal/install-cursor-skills.ts

@@ -1,10 +1,17 @@
 /**
  * Offer to install the package's coding-agent skills into the user's
- * personal Cursor skills dir under `~/.cursor/skills/agentkit/<skill>/`.
+ * personal Cursor skills dir under `~/.cursor/skills/agentsdk/<skill>/`.
  *
- * Cursor walks `~/.cursor/skills` recursively, so the `agentkit/` folder is
+ * Cursor walks `~/.cursor/skills` recursively, so the `agentsdk/` folder is
  * only organizational — identity comes from the leaf folder that holds
- * SKILL.md. Skipped for `--json` / non-TTY hosts.
+ * SKILL.md. Installed copies get `alwaysApply: true` so Cursor injects the
+ * skill body as a global rule instead of leaving it as an on-demand catalog
+ * entry. Skipped for `--json` / non-TTY hosts.
+ *
+ * Consumer installs (`npm install` / `npx` of `@cursor/july`) also copy
+ * these skills from a postinstall hook. That path never prompts and never
+ * fails the package install. The monorepo source checkout is not a consumer
+ * install, so `pnpm install` in everysphere does not overwrite `~/.cursor`.
  */
 
 import {
@@ -21,51 +28,86 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
+import { parseFrontmatter } from "./frontmatter.js";
 import { stdoutPalette } from "./terminal-style.js";
 
 /** Monorepo-only skill; excluded from the published package. */
 const SKIP_SKILL_DIRS = new Set(["operate"]);
 
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
-export const CURSOR_SKILLS_NAMESPACE = "agentkit";
+export const CURSOR_SKILLS_NAMESPACE = "agentsdk";
+
+/** Pre-rename install folder. Install deletes this so `/agentkit-*` rows disappear. */
+export const LEGACY_CURSOR_SKILLS_NAMESPACE = "agentkit";
 
 /** How long the `init` offer waits for an answer before skipping the install. */
 export const SKILL_PROMPT_TIMEOUT_MS = 45_000;
 
+/**
+ * Override the resolved `~/.cursor/skills` directory (not the user home).
+ * Used by the postinstall hook in tests and publish smoke.
+ */
+export const CURSOR_JULY_SKILLS_HOME_ENV = "CURSOR_JULY_SKILLS_HOME";
+
+/** Set to `1` to skip the postinstall skill copy. */
+export const CURSOR_JULY_SKIP_SKILL_INSTALL_ENV =
+  "CURSOR_JULY_SKIP_SKILL_INSTALL";
+
 export interface PackageSkill {
-  /** Frontmatter `name` (e.g. agentkit-create-agent). */
+  /** Frontmatter `name` (e.g. agentsdk-create-agent). */
   name: string;
-  /** Leaf install directory under agentkit/ (e.g. create-agent). */
+  /** Leaf install directory under agentsdk/ (e.g. create-agent). */
   leafDir: string;
   /** Absolute path to the source skill directory in the package. */
   sourceDir: string;
 }
 
-export function cursorSkillsHome(
-  home: string = process.env.HOME ?? homedir()
-): string {
-  const resolved = home.trim() === "" ? homedir() : home;
-  return join(resolved, ".cursor", "skills");
+export function cursorSkillsHome(home?: string): string {
+  if (home !== undefined) {
+    return join(home.trim() === "" ? homedir() : home, ".cursor", "skills");
+  }
+  const override = process.env[CURSOR_JULY_SKILLS_HOME_ENV]?.trim();
+  if (override !== undefined && override !== "") {
+    return override;
+  }
+  return join(homedir(), ".cursor", "skills");
+}
+
+/**
+ * True when this package root is an installed copy under `node_modules`
+ * (npm, pnpm, yarn, npx, global), not the everysphere source checkout.
+ */
+export function isConsumerPackageInstall(packageRoot: string): boolean {
+  // Segment check only — split on both separators so a Windows path still
+  // matches when this runs (or is tested) on POSIX. Do not rewrite the path.
+  return packageRoot.split(/[\\/]/).includes("node_modules");
 }
 
-/** `~/.cursor/skills/agentkit` — where package skills are installed. */
-export function agentkitCursorSkillsDir(
+/** `~/.cursor/skills/agentsdk` — where package skills are installed. */
+export function agentsdkCursorSkillsDir(
   skillsHome: string = cursorSkillsHome()
 ): string {
   return join(skillsHome, CURSOR_SKILLS_NAMESPACE);
 }
 
-/** Absolute install path for one skill: `…/agentkit/<leafDir>`. */
+/** Pre-rename `~/.cursor/skills/agentkit`. */
+export function legacyAgentkitCursorSkillsDir(
+  skillsHome: string = cursorSkillsHome()
+): string {
+  return join(skillsHome, LEGACY_CURSOR_SKILLS_NAMESPACE);
+}
+
+/** Absolute install path for one skill: `…/agentsdk/<leafDir>`. */
 export function skillInstallPath(
   skill: Pick<PackageSkill, "leafDir">,
   skillsHome: string = cursorSkillsHome()
 ): string {
-  return join(agentkitCursorSkillsDir(skillsHome), skill.leafDir);
+  return join(agentsdkCursorSkillsDir(skillsHome), skill.leafDir);
 }
 
 /**
  * Skills shipped next to the running package. Uses the frontmatter `name`
- * when present, otherwise `agentkit-<dir>`.
+ * when present, otherwise `agentsdk-<dir>`.
  */
 export async function listShippedPackageSkills(
   packageRoot: string = packageRootDir()
@@ -91,7 +133,9 @@ export async function listShippedPackageSkills(
       continue;
     }
     const raw = await readFile(skillMd, "utf8");
-    const name = parseSkillName(raw) ?? `agentkit-${entry.name}`;
+    const name =
+      parseFrontmatter(raw).data.name ||
+      `${CURSOR_SKILLS_NAMESPACE}-${entry.name}`;
     skills.push({ name, leafDir: entry.name, sourceDir });
   }
   skills.sort((a, b) => a.leafDir.localeCompare(b.leafDir));
@@ -99,7 +143,7 @@ export async function listShippedPackageSkills(
 }
 
 /**
- * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentkit/.
+ * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentsdk/.
  * Install still overwrites every shipped skill when the user confirms — this
  * helper is for messaging (fresh install vs update).
  */
@@ -125,18 +169,22 @@ export interface SkillInstallResult {
   installed: string[];
   /** Leaf dirs deleted because the package no longer ships them. */
   removed: string[];
+  /** True when leftover `~/.cursor/skills/agentkit` was deleted. */
+  removedLegacyNamespace: boolean;
 }
 
 /**
- * Copy each skill directory into `skillsHome/agentkit/<leafDir>/`.
+ * Copy each skill directory into `skillsHome/agentsdk/<leafDir>/`.
  * Always overwrites so a package upgrade refreshes local Cursor skills.
- * Strips monorepo-only frontmatter and removes leaf dirs no longer shipped.
+ * Strips monorepo-only frontmatter, sets `alwaysApply: true` so Cursor
+ * loads the body into context, and removes leaf dirs no longer shipped.
+ * Also deletes leftover `skillsHome/agentkit/` from the previous namespace.
  */
 export async function installCursorSkills(
   skills: readonly PackageSkill[],
   skillsHome: string = cursorSkillsHome()
 ): Promise<SkillInstallResult> {
-  const namespaceDir = agentkitCursorSkillsDir(skillsHome);
+  const namespaceDir = agentsdkCursorSkillsDir(skillsHome);
   await mkdir(namespaceDir, { recursive: true });
 
   const removed = await orphanLeaves(namespaceDir, skills);
@@ -161,7 +209,9 @@ export async function installCursorSkills(
     }
     installed.push(skill.leafDir);
   }
-  return { installed, removed };
+  const removedLegacyNamespace =
+    await removeLegacyCursorSkillsNamespace(skillsHome);
+  return { installed, removed, removedLegacyNamespace };
 }
 
 async function makeTreeWritable(root: string): Promise<void> {
@@ -202,13 +252,43 @@ async function orphanLeaves(
     .map((entry) => entry.name);
 }
 
-/** Drop monorepo `paths` globs and fix package doc links for ~/.cursor installs. */
+/** Drop leftover `skillsHome/agentkit` from the previous install namespace. */
+async function removeLegacyCursorSkillsNamespace(
+  skillsHome: string
+): Promise<boolean> {
+  const legacyDir = legacyAgentkitCursorSkillsDir(skillsHome);
+  try {
+    await stat(legacyDir);
+  } catch {
+    return false;
+  }
+  await rm(legacyDir, { recursive: true, force: true });
+  return true;
+}
+
+async function hasLegacyCursorSkillsNamespace(
+  skillsHome: string
+): Promise<boolean> {
+  try {
+    await stat(legacyAgentkitCursorSkillsDir(skillsHome));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drop monorepo `paths` globs, set `alwaysApply: true` so Cursor injects the
+ * body as a global rule, and fix package doc links for ~/.cursor installs.
+ */
 export function prepareSkillMarkdownForCursorInstall(content: string): string {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (match === null) {
     return content;
   }
-  const frontmatter = stripPathsFromFrontmatter(match[1] ?? "");
+  const frontmatter = withAlwaysApply(
+    stripPathsFromFrontmatter(match[1] ?? "")
+  );
   const body = content.slice(match[0].length);
   const adjustedBody = body.replace(
     /\[`docs\/([^`]+)`\]\(\.\.\/\.\.\/docs\/[^)]+\)/g,
@@ -235,11 +315,24 @@ function stripPathsFromFrontmatter(frontmatter: string): string {
   return out.join("\n");
 }
 
+/** Cursor loads `alwaysApply: true` skills as global rules, not catalog rows. */
+function withAlwaysApply(frontmatter: string): string {
+  const without = frontmatter
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*alwaysApply\s*:/.test(line))
+    .join("\n")
+    .replace(/\n+$/, "");
+  if (without === "") {
+    return "alwaysApply: true";
+  }
+  return `${without}\nalwaysApply: true`;
+}
+
 export interface SkillInstallPlan {
   shipped: PackageSkill[];
   /** Resolved `~/.cursor/skills`, to install into. */
   skillsHome: string;
-  /** Install target: `<skillsHome>/agentkit`. */
+  /** Install target: `<skillsHome>/agentsdk`. */
   directory: string;
   /** Leaf dirs the package ships. */
   leaves: string[];
@@ -247,6 +340,8 @@ export interface SkillInstallPlan {
   firstInstall: boolean;
   /** Installed leaf dirs the package dropped; installing deletes them. */
   orphans: string[];
+  /** True when leftover `skillsHome/agentkit` still exists. */
+  hasLegacyNamespace: boolean;
 }
 
 /** What an install would do, for the offer and for `install-skills`. */
@@ -255,19 +350,26 @@ export async function planSkillInstall(options?: {
   skillsHome?: string;
 }): Promise<SkillInstallPlan> {
   const skillsHome = options?.skillsHome ?? cursorSkillsHome();
-  const directory = agentkitCursorSkillsDir(skillsHome);
+  const directory = agentsdkCursorSkillsDir(skillsHome);
   const shipped = await listShippedPackageSkills(options?.packageRoot);
-  const missing = await findMissingCursorSkills({
-    packageRoot: options?.packageRoot,
-    skillsHome,
-  });
+  const present = await Promise.all(
+    shipped.map(async (skill) => {
+      try {
+        await access(join(skillInstallPath(skill, skillsHome), "SKILL.md"));
+        return true;
+      } catch {
+        return false;
+      }
+    })
+  );
   return {
     shipped,
     skillsHome,
     directory,
     leaves: shipped.map((skill) => skill.leafDir),
-    firstInstall: missing.length === shipped.length,
+    firstInstall: present.every((isPresent) => !isPresent),
     orphans: await orphanLeaves(directory, shipped),
+    hasLegacyNamespace: await hasLegacyCursorSkillsNamespace(skillsHome),
   };
 }
 
@@ -282,10 +384,73 @@ export function formatSkillInstall(
   if (result.removed.length > 0) {
     lines.push(`  removed:  ${result.removed.join(", ")}`);
   }
+  if (result.removedLegacyNamespace) {
+    lines.push(
+      `  removed:  ${legacyAgentkitCursorSkillsDir(plan.skillsHome)} (legacy namespace)`
+    );
+  }
   lines.push(`  location: ${plan.directory}`);
   return `${lines.join("\n")}\n`;
 }
 
+export type PackageInstallSkillSyncResult =
+  | { status: "installed"; installed: string[]; removed: string[] }
+  | {
+      status: "skipped";
+      reason: "opt-out" | "not-consumer" | "no-skills" | "error";
+    };
+
+export interface SyncCursorSkillsOnPackageInstallOptions {
+  packageRoot?: string;
+  skillsHome?: string;
+  env?: NodeJS.ProcessEnv;
+  /** Override the node_modules consumer check. */
+  consumer?: boolean;
+  out?: (text: string) => void;
+}
+
+/**
+ * Copy shipped coding-agent skills into ~/.cursor/skills/agentsdk during a
+ * consumer `npm install` / `npx`. Never throws: a failed copy must not fail
+ * the package install. No-op in the monorepo source tree and when
+ * `CURSOR_JULY_SKIP_SKILL_INSTALL=1`.
+ */
+export async function syncCursorSkillsOnPackageInstall(
+  options: SyncCursorSkillsOnPackageInstallOptions = {}
+): Promise<PackageInstallSkillSyncResult> {
+  try {
+    const env = options.env ?? process.env;
+    if (env[CURSOR_JULY_SKIP_SKILL_INSTALL_ENV] === "1") {
+      return { status: "skipped", reason: "opt-out" };
+    }
+
+    const packageRoot = options.packageRoot ?? packageRootDir();
+    const consumer = options.consumer ?? isConsumerPackageInstall(packageRoot);
+    if (!consumer) {
+      return { status: "skipped", reason: "not-consumer" };
+    }
+
+    const plan = await planSkillInstall({
+      packageRoot,
+      skillsHome: options.skillsHome,
+    });
+    if (plan.shipped.length === 0) {
+      return { status: "skipped", reason: "no-skills" };
+    }
+
+    const result = await installCursorSkills(plan.shipped, plan.skillsHome);
+    const out = options.out ?? ((text) => process.stderr.write(text));
+    out(formatSkillInstall(plan, result));
+    return {
+      status: "installed",
+      installed: result.installed,
+      removed: result.removed,
+    };
+  } catch {
+    return { status: "skipped", reason: "error" };
+  }
+}
+
 export interface OfferInstallCursorSkillsOptions {
   /** Skip when false (non-TTY / `--json`). */
   interactive?: boolean;
@@ -298,7 +463,7 @@ export interface OfferInstallCursorSkillsOptions {
 
 /**
  * On a TTY, offer to install/update every shipped package skill into
- * ~/.cursor/skills/agentkit (always overwriting). No-op when non-interactive
+ * ~/.cursor/skills/agentsdk (always overwriting). No-op when non-interactive
  * or the package ships no skills. An unanswered prompt skips the install
  * rather than blocking the caller — see `SKILL_PROMPT_TIMEOUT_MS`.
  */
@@ -334,6 +499,13 @@ export async function offerInstallCursorSkills(
   if (plan.orphans.length > 0) {
     out(c.dim(`  (deletes ${plan.orphans.join(", ")})\n`));
   }
+  if (plan.hasLegacyNamespace) {
+    out(
+      c.dim(
+        `  (deletes leftover ${legacyAgentkitCursorSkillsDir(plan.skillsHome)})\n`
+      )
+    );
+  }
 
   const confirm =
     options.confirm ??
@@ -365,23 +537,6 @@ export async function offerInstallCursorSkills(
   return { installed: result.installed, skipped: false };
 }
 
-function parseSkillName(skillMd: string): string | undefined {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
-  if (match === null) {
-    return undefined;
-  }
-  const nameLine = /^name:\s*(.+)\s*$/m.exec(match[1] ?? "");
-  if (nameLine === null) {
-    return undefined;
-  }
-  const raw = nameLine[1]?.trim();
-  if (raw === undefined || raw === "") {
-    return undefined;
-  }
-  // Strip optional quotes around the YAML scalar.
-  return raw.replace(/^["']|["']$/g, "");
-}
-
 export interface PromptYesNoOptions {
   defaultYes: boolean;
   out: (text: string) => void;

package/src/internal/json-schema.ts

@@ -29,15 +29,36 @@ export function toolInputJsonSchema(
   if (inputSchema === undefined) {
     return ANY_OBJECT_SCHEMA;
   }
-  if (isZodSchema(inputSchema)) {
-    const converted = zodToJsonSchema(inputSchema as z.ZodTypeAny, {
+  return authoredSchemaToJsonSchema(inputSchema);
+}
+
+/**
+ * Convert an authored output schema into the JSON Schema advertised on the
+ * tool. Unlike {@link toolInputJsonSchema} there is no fallback: an
+ * undeclared output schema stays undeclared (the MCP field is optional), and
+ * outputs are never validated against it.
+ */
+export function toolOutputJsonSchema(
+  outputSchema: z.ZodTypeAny | JsonSchemaObject | undefined
+): JsonSchemaObject | undefined {
+  if (outputSchema === undefined) {
+    return undefined;
+  }
+  return authoredSchemaToJsonSchema(outputSchema);
+}
+
+function authoredSchemaToJsonSchema(
+  schema: z.ZodTypeAny | JsonSchemaObject
+): JsonSchemaObject {
+  if (isZodSchema(schema)) {
+    const converted = zodToJsonSchema(schema as z.ZodTypeAny, {
       $refStrategy: "none",
       target: "jsonSchema7",
     }) as Record<string, unknown>;
     delete converted.$schema;
     return converted;
   }
-  return inputSchema;
+  return schema;
 }
 
 export type ToolInputValidation =

package/src/internal/mcp-endpoint.ts

@@ -218,6 +218,9 @@ function buildToolMcpServer(
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined
+          ? {}
+          : { outputSchema: tool.outputSchema }),
       })),
     })
   );
@@ -298,6 +301,9 @@ function buildConnectionBridgeMcpServer(
           ? {}
           : { description: tool.description }),
         inputSchema: tool.inputSchema ?? { type: "object" },
+        ...(tool.outputSchema === undefined
+          ? {}
+          : { outputSchema: tool.outputSchema }),
       })),
     };
   });

package/src/internal/mcp-host.ts

@@ -217,6 +217,7 @@ function toToolInfo(tool: {
   name: string;
   description?: string;
   inputSchema?: unknown;
+  outputSchema?: unknown;
 }): HostMcpToolInfo {
   return {
     name: tool.name,
@@ -226,6 +227,9 @@ function toToolInfo(tool: {
     ...(tool.inputSchema === undefined
       ? {}
       : { inputSchema: tool.inputSchema as JsonObject }),
+    ...(tool.outputSchema === undefined
+      ? {}
+      : { outputSchema: tool.outputSchema as JsonObject }),
   };
 }
 

package/src/internal/mcp-oauth.ts

@@ -259,8 +259,52 @@ type ProviderArgs = {
   onRedirect?: (url: URL) => void;
   tokens?: OAuthTokens;
   clientInformation?: OAuthClientInformationFull;
+  /**
+   * True when authorize/token requests must NOT carry the RFC 8707
+   * `resource` indicator, read off the server's protected-resource
+   * metadata (`cursor_omit_resource_indicator`). Entra rejects the
+   * indicator with AADSTS9010010, so Microsoft 365 flows through Cursor's
+   * REST-as-MCP translator fail pre-auth without this.
+   */
+  omitResourceIndicator?: boolean;
 };
 
+/**
+ * Reads the Cursor REST-as-MCP translator's OAuth quirk off the resource's
+ * RFC 9728 protected-resource metadata. Deliberately self-contained
+ * (`@cursor/july` publishes to public npm with no private workspace
+ * dependencies — see `waitForMcpOAuthCallback`): matches the translator
+ * path shape on any origin so local translators work, and fails to the
+ * default behavior (indicator kept) when the PRM is unreachable.
+ */
+export async function fetchOmitResourceIndicatorFromPrm(
+  resourceUrl: string,
+  fetchImpl: typeof fetch = fetch
+): Promise<boolean> {
+  let url: URL;
+  try {
+    url = new URL(resourceUrl);
+  } catch {
+    return false;
+  }
+  if (!/^\/rest-mcp\/[^/]+\/mcp\/?$/.test(url.pathname)) {
+    return false;
+  }
+  const prmUrl = `${url.origin}/.well-known/oauth-protected-resource${url.pathname.replace(/\/+$/, "")}`;
+  try {
+    const response = await fetchImpl(prmUrl);
+    if (!response.ok) {
+      return false;
+    }
+    const document = (await response.json()) as {
+      cursor_omit_resource_indicator?: unknown;
+    };
+    return document.cursor_omit_resource_indicator === true;
+  } catch {
+    return false;
+  }
+}
+
 export class HostMcpOAuthProvider implements OAuthClientProvider {
   private tokensValue: OAuthTokens | undefined;
   private clientInfo: OAuthClientInformationFull | undefined;
@@ -268,11 +312,19 @@ export class HostMcpOAuthProvider implements OAuthClientProvider {
   private redirect: URL | undefined;
   private readonly meta: OAuthClientMetadata;
   private readonly args: ProviderArgs;
+  /**
+   * Assigned only when the PRM sets `cursor_omit_resource_indicator`; left
+   * absent otherwise so the SDK's default resource validation applies.
+   */
+  readonly validateResourceURL: (() => Promise<URL | undefined>) | undefined;
 
   constructor(args: ProviderArgs) {
     this.args = args;
     this.tokensValue = args.tokens;
     this.clientInfo = args.clientInformation;
+    if (args.omitResourceIndicator === true) {
+      this.validateResourceURL = async () => undefined;
+    }
     this.meta = {
       redirect_uris: [args.redirectUrl ?? MCP_OAUTH_CALLBACK_URL],
       token_endpoint_auth_method: "none",
@@ -366,9 +418,10 @@ export async function createHostMcpOAuthProvider(args: {
   onRedirect?: (url: URL) => void;
 }): Promise<HostMcpOAuthProvider> {
   const store = args.store ?? new FileMcpOAuthStore();
-  const [fileTokens, fileClient] = await Promise.all([
+  const [fileTokens, fileClient, omitResourceIndicator] = await Promise.all([
     store.loadTokens(args.identifier, args.resourceUrl),
     store.loadClientInformation(args.identifier, args.resourceUrl),
+    fetchOmitResourceIndicatorFromPrm(args.resourceUrl),
   ]);
   return new HostMcpOAuthProvider({
     identifier: args.identifier,
@@ -377,6 +430,7 @@ export async function createHostMcpOAuthProvider(args: {
     tokens: fileTokens ?? tokensFromEnv(args.identifier),
     clientInformation: fileClient ?? clientIdFromEnv(args.identifier),
     onRedirect: args.onRedirect,
+    omitResourceIndicator,
   });
 }
 

package/src/internal/package-inline-stdio.ts

@@ -14,7 +14,7 @@ import type {
   JsonSchemaObject,
 } from "../types.js";
 import type { InlineStdioCatalogEntry } from "./inline-stdio-mcp.js";
-import { toolInputJsonSchema } from "./json-schema.js";
+import { toolInputJsonSchema, toolOutputJsonSchema } from "./json-schema.js";
 
 const require = createRequire(import.meta.url);
 
@@ -35,9 +35,13 @@ function jsonSchemaCatalog(
 ): Record<string, InlineStdioCatalogEntry> {
   const catalog: Record<string, InlineStdioCatalogEntry> = {};
   for (const [name, tool] of Object.entries(tools)) {
+    const outputSchema = toolOutputJsonSchema(tool.outputSchema);
     catalog[name] = {
       description: tool.description,
       inputSchema: toolInputJsonSchema(tool.inputSchema) as JsonSchemaObject,
+      ...(outputSchema === undefined
+        ? {}
+        : { outputSchema: outputSchema as JsonSchemaObject }),
     };
   }
   return catalog;