@cursor/july 0.1.73 → 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/sdk-runner.ts

@@ -14,12 +14,12 @@ import {
   type CloudAgentOptions,
   Cursor,
   createAgentPlatform,
-  JsonlLocalAgentStore,
   type LocalAgentStore,
   type ModelSelection,
   type RunResult,
   type SDKAgent,
 } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import {
   DEFAULT_MODEL,
   type ModelSetting,
@@ -558,8 +558,11 @@ export class CursorSdkRunner implements AgentRunner {
   private getStore(stateDir: string): Promise<LocalAgentStore> {
     let storePromise = this.stores.get(stateDir);
     if (storePromise === undefined) {
-      storePromise = mkdir(stateDir, { recursive: true }).then(
-        () => new JsonlLocalAgentStore(stateDir)
+      storePromise = mkdir(stateDir, { recursive: true }).then(() =>
+        SqliteLocalAgentStore.open({
+          stateRoot: stateDir,
+          workspaceRef: stateDir,
+        })
       );
       this.stores.set(stateDir, storePromise);
     }