@cursor/july 0.1.18 → 0.1.20

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

@@ -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();
+    }
   });
 }