npm - @cursor/july - Versions diffs - 0.1.18 → 0.1.19 - Mend

@cursor/july 0.1.18 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/dist/bin/agent-serve.js +20 -3
package/dist/docs/404.html +1 -1
package/dist/docs/ab.html +2 -2
package/dist/docs/assets/{app.BR5EdVSq.js → app.CrsWMchO.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.BnHRjfoe.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.CNCzfUKC.js → VPLocalSearchBox.D1JqzSh8.js} +1 -1
package/dist/docs/assets/chunks/{theme.CwKvMSWv.js → theme.DaBvZYwl.js} +2 -2
package/dist/docs/building-with-agents.html +2 -2
package/dist/docs/concepts.html +2 -2
package/dist/docs/deployment.html +2 -2
package/dist/docs/evals.html +2 -2
package/dist/docs/example-agents/approval-buddy.html +2 -2
package/dist/docs/example-agents/benny.html +2 -2
package/dist/docs/example-agents/bugbot.html +2 -2
package/dist/docs/example-agents/codebase-wiki.html +2 -2
package/dist/docs/example-agents/codeowners-review.html +2 -2
package/dist/docs/example-agents/concierge.html +2 -2
package/dist/docs/example-agents/fsd.html +2 -2
package/dist/docs/example-agents/index.html +2 -2
package/dist/docs/example-agents/knowledge-base.html +2 -2
package/dist/docs/example-agents/oncall.html +2 -2
package/dist/docs/example-agents/security-reviewer.html +2 -2
package/dist/docs/example-agents/slack-agent.html +2 -2
package/dist/docs/example-agents/weather-agent.html +2 -2
package/dist/docs/guides/agent-to-agent.html +2 -2
package/dist/docs/guides/cloud-runtime.html +2 -2
package/dist/docs/guides/github.html +2 -2
package/dist/docs/guides/human-in-the-loop.html +2 -2
package/dist/docs/guides/mcp-oauth.html +2 -2
package/dist/docs/guides/slack.html +2 -2
package/dist/docs/guides/webhooks.html +2 -2
package/dist/docs/hillclimbing.html +2 -2
package/dist/docs/index.html +2 -2
package/dist/docs/quickstart.html +2 -2
package/dist/docs/reference/agent-config.html +2 -2
package/dist/docs/reference/channels.html +2 -2
package/dist/docs/reference/cli.html +2 -2
package/dist/docs/reference/connections.html +2 -2
package/dist/docs/reference/hooks.html +2 -2
package/dist/docs/reference/http-api.html +2 -2
package/dist/docs/reference/instructions.html +2 -2
package/dist/docs/reference/playground.html +2 -2
package/dist/docs/reference/project-layout.html +2 -2
package/dist/docs/reference/prompt.html +2 -2
package/dist/docs/reference/schedules.html +2 -2
package/dist/docs/reference/sessions.html +2 -2
package/dist/docs/reference/skills.html +2 -2
package/dist/docs/reference/subagents.html +2 -2
package/dist/docs/reference/tools.html +2 -2
package/dist/docs/scaffolding-agents.html +2 -2
package/dist/docs/storage.html +2 -2
package/dist/docs/troubleshooting.html +2 -2
package/dist/internal/cli-skills.d.ts +19 -0
package/dist/internal/cli-skills.d.ts.map +1 -0
package/dist/internal/cli-skills.js +72 -0
package/dist/internal/install-cursor-skills.d.ts +46 -4
package/dist/internal/install-cursor-skills.d.ts.map +1 -1
package/dist/internal/install-cursor-skills.js +117 -49
package/dist/playground/assets/{index-DRjS5klQ.js → index-C2SU2xV5.js} +23 -23
package/dist/playground/assets/index-CidizGZv.css +1 -0
package/dist/playground/index.html +2 -2
package/package.json +1 -1
package/src/bin/agent-serve.ts +21 -3
package/src/internal/cli-skills.ts +95 -0
package/src/internal/install-cursor-skills.ts +168 -60
package/dist/docs/assets/chunks/@localSearchIndexroot.BOzkeUi8.js +0 -1
package/dist/playground/assets/index-TCDs-UhZ.css +0 -1

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-DRjS5klQ.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-TCDs-UhZ.css">
+    <script type="module" crossorigin src="./assets/index-C2SU2xV5.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CidizGZv.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/bin/agent-serve.ts CHANGED Viewed

@@ -94,6 +94,7 @@ Usage:
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
   ${CLI} init        [dir] [--json]
+  ${CLI} install-skills [--print] [--json]
   ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
                           | --url <baseUrl> [--bearer-token <t>]
   ${CLI} mcp install [--name <serverName>] [--print] [--json]
@@ -173,6 +174,12 @@ Commands:
               run login when unsigned, then print next steps. --json is
               machine-readable and never blocks on login. No directory:
               print the setup guide.
+  install-skills
+              Install (or refresh) the agentkit skills for coding agents in
+              ~/.cursor/skills/agentkit and print where they landed. \`init\`
+              offers this once, interactively, and skips it when the prompt
+              goes unanswered; this command never asks. --print previews
+              without writing.
   mcp         Serve this agent's MCP endpoint over stdio for MCP clients
               that spawn local servers (e.g. Cursor). Proxies
               newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
@@ -291,6 +298,8 @@ Options:
   --once             logs: print current progress / log buffer once and exit
                      (default is to follow).
   --print            playground: print the URL only; do not open a browser.
+                     install-skills: list the skills and the install path
+                     without writing them.
   --no-wait          deploy/stop/eval: return right after the request is
                      accepted instead of polling until a terminal status.
                      For eval, prints the runId (deployment / --url only).
@@ -332,9 +341,10 @@ Options:
   --no-artifacts     eval: do not write run artifacts.
   --skip-report      eval: ignore reporters from evals.config.ts / eval files.
   --no-stream        run/eval: silence live progress on stderr (JSON still prints).
-  --json             JSON output (init/info/chat/eval/logs/sessions/session/
-                     github; run defaults to JSON). logs: NDJSON progress/log
-                     events. session: trajectory JSON (not raw events).
+  --json             JSON output (init/install-skills/info/chat/eval/logs/
+                     sessions/session/github; run defaults to JSON). logs:
+                     NDJSON progress/log events. session: trajectory JSON
+                     (not raw events).
   --no-color         chat: force plain output.
   --cursor-events    serve: pull SCM webhook events from /v0/scm-events. The
                      stream is read as your Cursor user, so serve requires
@@ -558,6 +568,14 @@ async function main(argv: string[]): Promise<number> {
       });
     }
+    case "install-skills": {
+      const { cmdInstallSkills } = await import("../internal/cli-skills.js");
+      return cmdInstallSkills({
+        json: values.json,
+        print: values.print,
+      });
+    }
     case "mcp": {
       const { cmdMcp } = await import("../internal/cli-mcp.js");
       const mcpSub = positionals[0];

package/src/internal/cli-skills.ts ADDED Viewed

@@ -0,0 +1,95 @@
+/**
+ * `install-skills` — install the package's coding-agent skills into
+ * `~/.cursor/skills/agentkit/` without running `init`.
+ *
+ * Never prompts: running the command is the confirmation. The interactive
+ * offer lives in `init`.
+ */
+import { CLI_COMMAND_NAME } from "./distribution.js";
+import {
+  formatSkillInstall,
+  installCursorSkills,
+  planSkillInstall,
+  type SkillInstallPlan,
+} from "./install-cursor-skills.js";
+import { stdoutPalette } from "./terminal-style.js";
+export interface InstallSkillsCliOptions {
+  json?: boolean;
+  /** Preview the skills, the removals, and the install address; write nothing. */
+  print?: boolean;
+  /** Injected seams for tests. */
+  packageRoot?: string;
+  skillsHome?: string;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+}
+export async function cmdInstallSkills(
+  options: InstallSkillsCliOptions = {}
+): Promise<number> {
+  const out = options.out ?? ((text) => process.stdout.write(text));
+  const err = options.err ?? ((text) => process.stderr.write(text));
+  const plan = await planSkillInstall({
+    packageRoot: options.packageRoot,
+    skillsHome: options.skillsHome,
+  });
+  if (plan.shipped.length === 0) {
+    err(`${CLI_COMMAND_NAME} ships no skills to install.\n`);
+    return 1;
+  }
+  const emit = (run: { dryRun: boolean; removed: string[] }): void => {
+    const payload: SkillInstallPayload = {
+      ok: true,
+      dryRun: run.dryRun,
+      directory: plan.directory,
+      firstInstall: plan.firstInstall,
+      skills: plan.leaves,
+      removed: run.removed,
+    };
+    out(`${JSON.stringify(payload, null, 2)}\n`);
+  };
+  const noun = plan.shipped.length === 1 ? "skill" : "skills";
+  if (options.print === true) {
+    if (options.json === true) {
+      emit({ dryRun: true, removed: plan.orphans });
+      return 0;
+    }
+    const action = plan.firstInstall ? "install" : "update";
+    out(`Would ${action} ${plan.leaves.length} agentkit ${noun}\n`);
+    out(previewBlock(plan));
+    return 0;
+  }
+  const result = await installCursorSkills(plan.shipped, plan.skillsHome);
+  if (options.json === true) {
+    emit({ dryRun: false, removed: result.removed });
+    return 0;
+  }
+  out(formatSkillInstall(plan, result));
+  return 0;
+}
+interface SkillInstallPayload {
+  ok: true;
+  /** True when `--print` previewed the install instead of running it. */
+  dryRun: boolean;
+  directory: string;
+  firstInstall: boolean;
+  skills: string[];
+  removed: string[];
+}
+function previewBlock(plan: SkillInstallPlan): string {
+  const c = stdoutPalette();
+  const lines = [c.dim(`  skills:   ${plan.leaves.join(", ")}`)];
+  if (plan.orphans.length > 0) {
+    lines.push(`  removes:  ${plan.orphans.join(", ")}`);
+  }
+  lines.push(`  location: ${plan.directory}`);
+  return `${lines.join("\n")}\n`;
+}

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

@@ -18,7 +18,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { packageRootDir } from "./distribution.js";
+import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
 import { stdoutPalette } from "./terminal-style.js";
 /** Monorepo-only skill; excluded from the published package. */
@@ -27,6 +27,9 @@ const SKIP_SKILL_DIRS = new Set(["operate"]);
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
 export const 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;
 export interface PackageSkill {
   /** Frontmatter `name` (e.g. agentkit-create-agent). */
   name: string;
@@ -115,6 +118,13 @@ export async function findMissingCursorSkills(options?: {
   return missing;
 }
+export interface SkillInstallResult {
+  /** Leaf dirs written. */
+  installed: string[];
+  /** Leaf dirs deleted because the package no longer ships them. */
+  removed: string[];
+}
 /**
  * Copy each skill directory into `skillsHome/agentkit/<leafDir>/`.
  * Always overwrites so a package upgrade refreshes local Cursor skills.
@@ -123,24 +133,13 @@ export async function findMissingCursorSkills(options?: {
 export async function installCursorSkills(
   skills: readonly PackageSkill[],
   skillsHome: string = cursorSkillsHome()
-): Promise<string[]> {
+): Promise<SkillInstallResult> {
   const namespaceDir = agentkitCursorSkillsDir(skillsHome);
   await mkdir(namespaceDir, { recursive: true });
-  const shippedLeaves = new Set(skills.map((skill) => skill.leafDir));
-  let existingLeaves: string[] = [];
-  try {
-    const entries = await readdir(namespaceDir, { withFileTypes: true });
-    existingLeaves = entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
-  } catch {
-    existingLeaves = [];
-  }
-  for (const leaf of existingLeaves) {
-    if (!shippedLeaves.has(leaf)) {
-      await rm(join(namespaceDir, leaf), { recursive: true, force: true });
-    }
+  const removed = await orphanLeaves(namespaceDir, skills);
+  for (const leaf of removed) {
+    await rm(join(namespaceDir, leaf), { recursive: true, force: true });
   }
   const installed: string[] = [];
@@ -155,7 +154,24 @@ export async function installCursorSkills(
     }
     installed.push(skill.leafDir);
   }
-  return installed;
+  return { installed, removed };
+}
+/** Installed leaf dirs the package no longer ships. Installing deletes these. */
+async function orphanLeaves(
+  namespaceDir: string,
+  skills: readonly PackageSkill[]
+): Promise<string[]> {
+  const shipped = new Set(skills.map((skill) => skill.leafDir));
+  let entries: Array<{ name: string; isDirectory: () => boolean }>;
+  try {
+    entries = await readdir(namespaceDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && !shipped.has(entry.name))
+    .map((entry) => entry.name);
 }
 /** Drop monorepo `paths` globs and fix package doc links for ~/.cursor installs. */
@@ -191,20 +207,72 @@ function stripPathsFromFrontmatter(frontmatter: string): string {
   return out.join("\n");
 }
+export interface SkillInstallPlan {
+  shipped: PackageSkill[];
+  /** Resolved `~/.cursor/skills`, to install into. */
+  skillsHome: string;
+  /** Install target: `<skillsHome>/agentkit`. */
+  directory: string;
+  /** Leaf dirs the package ships. */
+  leaves: string[];
+  /** Nothing installed yet, so this is a fresh install rather than a refresh. */
+  firstInstall: boolean;
+  /** Installed leaf dirs the package dropped; installing deletes them. */
+  orphans: string[];
+}
+/** What an install would do, for the offer and for `install-skills`. */
+export async function planSkillInstall(options?: {
+  packageRoot?: string;
+  skillsHome?: string;
+}): Promise<SkillInstallPlan> {
+  const skillsHome = options?.skillsHome ?? cursorSkillsHome();
+  const directory = agentkitCursorSkillsDir(skillsHome);
+  const shipped = await listShippedPackageSkills(options?.packageRoot);
+  const missing = await findMissingCursorSkills({
+    packageRoot: options?.packageRoot,
+    skillsHome,
+  });
+  return {
+    shipped,
+    skillsHome,
+    directory,
+    leaves: shipped.map((skill) => skill.leafDir),
+    firstInstall: missing.length === shipped.length,
+    orphans: await orphanLeaves(directory, shipped),
+  };
+}
+/** `Installed 9 agentkit skills`, what it dropped, and where it went. */
+export function formatSkillInstall(
+  plan: SkillInstallPlan,
+  result: SkillInstallResult
+): string {
+  const noun = result.installed.length === 1 ? "skill" : "skills";
+  const verb = plan.firstInstall ? "Installed" : "Updated";
+  const lines = [`${verb} ${result.installed.length} agentkit ${noun}`];
+  if (result.removed.length > 0) {
+    lines.push(`  removed:  ${result.removed.join(", ")}`);
+  }
+  lines.push(`  location: ${plan.directory}`);
+  return `${lines.join("\n")}\n`;
+}
 export interface OfferInstallCursorSkillsOptions {
   /** Skip when false (non-TTY / `--json`). */
   interactive?: boolean;
   packageRoot?: string;
   skillsHome?: string;
-  /** Injected yes/no for tests. */
-  confirm?: (question: string) => Promise<boolean>;
+  /** Injected yes/no for tests. `undefined` means the prompt went unanswered. */
+  confirm?: (question: string) => Promise<boolean | undefined>;
   out?: (text: string) => void;
 }
 /**
  * On a TTY, offer to install/update every shipped package skill into
  * ~/.cursor/skills/agentkit (always overwriting). No-op when non-interactive
- * or the package ships no skills.
+ * or the package ships no skills. An unanswered prompt skips the install
+ * rather than blocking the caller — see `SKILL_PROMPT_TIMEOUT_MS`.
  */
 export async function offerInstallCursorSkills(
   options: OfferInstallCursorSkillsOptions = {}
@@ -213,48 +281,60 @@ export async function offerInstallCursorSkills(
   const interactive =
     options.interactive ??
     (process.stdin.isTTY === true && process.stdout.isTTY === true);
-  const shipped = await listShippedPackageSkills(options.packageRoot);
-  if (shipped.length === 0) {
+  if (!interactive) {
     return { installed: [], skipped: true };
   }
-  const home = options.skillsHome ?? cursorSkillsHome();
-  const targetDir = agentkitCursorSkillsDir(home);
-  const missing = await findMissingCursorSkills({
+  const plan = await planSkillInstall({
     packageRoot: options.packageRoot,
-    skillsHome: home,
+    skillsHome: options.skillsHome,
   });
-  const names = shipped.map((skill) => skill.leafDir).join(", ");
-  const noun = shipped.length === 1 ? "skill" : "skills";
-  const verb = missing.length === shipped.length ? "Install" : "Update";
-  const question = `${verb} ${shipped.length} agentkit ${noun} in ${targetDir}?`;
-  if (!interactive) {
+  if (plan.shipped.length === 0) {
     return { installed: [], skipped: true };
   }
+  const noun = plan.shipped.length === 1 ? "skill" : "skills";
+  const verb = plan.firstInstall ? "Install" : "Update";
   const c = stdoutPalette();
-  out(`${question}\n`);
-  out(c.dim(`  ${names}\n`));
-  if (missing.length < shipped.length) {
+  out(
+    `${verb} ${plan.shipped.length} agentkit ${noun} in ${plan.directory}?\n`
+  );
+  out(c.dim(`  ${plan.leaves.join(", ")}\n`));
+  if (!plan.firstInstall) {
     out(c.dim("  (overwrites existing copies with the package version)\n"));
   }
+  if (plan.orphans.length > 0) {
+    out(c.dim(`  (deletes ${plan.orphans.join(", ")})\n`));
+  }
   const confirm =
-    options.confirm ?? ((q) => promptYesNo(q, { defaultYes: true, out }));
-  const accepted = await confirm(
-    missing.length === shipped.length ? "Install now?" : "Update now?"
-  );
-  if (!accepted) {
-    out(c.dim("Skipped skill install.\n\n"));
+    options.confirm ??
+    ((q) =>
+      promptYesNo(q, {
+        defaultYes: true,
+        out,
+        timeoutMs: SKILL_PROMPT_TIMEOUT_MS,
+      }));
+  const accepted = await confirm(`${verb} now?`);
+  if (accepted !== true) {
+    // `undefined` is the prompt timing out or stdin closing; both mean nobody
+    // said yes, so do not claim a duration neither case is guaranteed to have.
+    const why =
+      accepted === undefined
+        ? "No answer — skipped the skill install."
+        : "Skipped skill install.";
+    out(
+      c.dim(
+        `${why}\nInstall later: ${CLI_COMMAND_NAME} install-skills (${plan.directory})\n\n`
+      )
+    );
     return { installed: [], skipped: true };
   }
-  const installed = await installCursorSkills(shipped, home);
-  out(
-    `${verb === "Install" ? "Installed" : "Updated"} ${installed.length} ${noun} in ${targetDir}\n\n`
-  );
-  return { installed, skipped: false };
+  const result = await installCursorSkills(plan.shipped, plan.skillsHome);
+  out(`${formatSkillInstall(plan, result)}\n`);
+  return { installed: result.installed, skipped: false };
 }
 function parseSkillName(skillMd: string): string | undefined {
@@ -274,19 +354,34 @@ function parseSkillName(skillMd: string): string | undefined {
   return raw.replace(/^["']|["']$/g, "");
 }
-async function promptYesNo(
+export interface PromptYesNoOptions {
+  defaultYes: boolean;
+  out: (text: string) => void;
+  /** Give up after this long; `0` (or omitted) waits forever. */
+  timeoutMs?: number;
+  /** Answer source; defaults to `process.stdin`. */
+  input?: NodeJS.ReadableStream;
+}
+/**
+ * Ask a yes/no question. Resolves `undefined` when the answer never comes —
+ * the prompt timed out, or stdin closed on an empty line.
+ */
+export async function promptYesNo(
   question: string,
-  options: {
-    defaultYes: boolean;
-    out: (text: string) => void;
-  }
-): Promise<boolean> {
+  options: PromptYesNoOptions
+): Promise<boolean | undefined> {
   const hint = options.defaultYes ? "Y/n" : "y/N";
+  const input = options.input ?? process.stdin;
   options.out(`${question} [${hint}] `);
-  process.stdin.resume();
-  const line = await readOneLine(process.stdin);
-  process.stdin.pause();
-  if (line === undefined || line.trim() === "") {
+  input.resume();
+  const line = await readOneLine(input, options.timeoutMs);
+  input.pause();
+  if (line === undefined) {
+    options.out("\n");
+    return undefined;
+  }
+  if (line.trim() === "") {
     return options.defaultYes;
   }
   const answer = line.trim().toLowerCase();
@@ -299,11 +394,14 @@ async function promptYesNo(
   return options.defaultYes;
 }
+/** The line, or `undefined` when the stream ends or the clock runs out first. */
 function readOneLine(
-  stream: NodeJS.ReadableStream
+  stream: NodeJS.ReadableStream,
+  timeoutMs?: number
 ): Promise<string | undefined> {
   return new Promise((resolve) => {
     let buffer = "";
+    let timer: NodeJS.Timeout | undefined;
     const onData = (chunk: string | Buffer): void => {
       buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
       const newline = buffer.indexOf("\n");
@@ -313,15 +411,25 @@ function readOneLine(
       cleanup();
       resolve(buffer.slice(0, newline).replace(/\r$/, ""));
     };
-    const onEnd = (): void => {
+    // EOF and the timeout both land here. A tty holds a half-typed line until
+    // Enter, so a non-empty buffer only ever happens on piped input.
+    const giveUp = (): void => {
       cleanup();
       resolve(buffer === "" ? undefined : buffer.replace(/\r$/, ""));
     };
     const cleanup = (): void => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
       stream.off("data", onData);
-      stream.off("end", onEnd);
+      stream.off("end", giveUp);
     };
     stream.on("data", onData);
-    stream.on("end", onEnd);
+    stream.on("end", giveUp);
+    if (timeoutMs !== undefined && timeoutMs > 0) {
+      timer = setTimeout(giveUp, timeoutMs);
+      // Never keep the process alive purely to wait for an answer.
+      timer.unref();
+    }
   });
 }