@cursor/july 0.1.2 → 0.1.4

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

@@ -0,0 +1,327 @@
+/**
+ * Offer to install the package's coding-agent skills into the user's
+ * personal Cursor skills dir under `~/.cursor/skills/agentkit/<skill>/`.
+ *
+ * Cursor walks `~/.cursor/skills` recursively, so the `agentkit/` folder is
+ * only organizational — identity comes from the leaf folder that holds
+ * SKILL.md. Skipped for `--json` / non-TTY hosts.
+ */
+
+import {
+  access,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { packageRootDir } from "./distribution.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 interface PackageSkill {
+  /** Frontmatter `name` (e.g. agentkit-create-agent). */
+  name: string;
+  /** Leaf install directory under agentkit/ (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");
+}
+
+/** `~/.cursor/skills/agentkit` — where package skills are installed. */
+export function agentkitCursorSkillsDir(
+  skillsHome: string = cursorSkillsHome()
+): string {
+  return join(skillsHome, CURSOR_SKILLS_NAMESPACE);
+}
+
+/** Absolute install path for one skill: `…/agentkit/<leafDir>`. */
+export function skillInstallPath(
+  skill: Pick<PackageSkill, "leafDir">,
+  skillsHome: string = cursorSkillsHome()
+): string {
+  return join(agentkitCursorSkillsDir(skillsHome), skill.leafDir);
+}
+
+/**
+ * Skills shipped next to the running package. Uses the frontmatter `name`
+ * when present, otherwise `agentkit-<dir>`.
+ */
+export async function listShippedPackageSkills(
+  packageRoot: string = packageRootDir()
+): Promise<PackageSkill[]> {
+  const skillsRoot = join(packageRoot, "skills");
+  let entries: Array<{ name: string; isDirectory: () => boolean }>;
+  try {
+    entries = await readdir(skillsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const skills: PackageSkill[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || SKIP_SKILL_DIRS.has(entry.name)) {
+      continue;
+    }
+    const sourceDir = join(skillsRoot, entry.name);
+    const skillMd = join(sourceDir, "SKILL.md");
+    try {
+      await access(skillMd);
+    } catch {
+      continue;
+    }
+    const raw = await readFile(skillMd, "utf8");
+    const name = parseSkillName(raw) ?? `agentkit-${entry.name}`;
+    skills.push({ name, leafDir: entry.name, sourceDir });
+  }
+  skills.sort((a, b) => a.leafDir.localeCompare(b.leafDir));
+  return skills;
+}
+
+/**
+ * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentkit/.
+ * Install still overwrites every shipped skill when the user confirms — this
+ * helper is for messaging (fresh install vs update).
+ */
+export async function findMissingCursorSkills(options?: {
+  packageRoot?: string;
+  skillsHome?: string;
+}): Promise<PackageSkill[]> {
+  const shipped = await listShippedPackageSkills(options?.packageRoot);
+  const home = options?.skillsHome ?? cursorSkillsHome();
+  const missing: PackageSkill[] = [];
+  for (const skill of shipped) {
+    try {
+      await access(join(skillInstallPath(skill, home), "SKILL.md"));
+    } catch {
+      missing.push(skill);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Copy each skill directory into `skillsHome/agentkit/<leafDir>/`.
+ * Always overwrites so a package upgrade refreshes local Cursor skills.
+ * Strips monorepo-only frontmatter and removes leaf dirs no longer shipped.
+ */
+export async function installCursorSkills(
+  skills: readonly PackageSkill[],
+  skillsHome: string = cursorSkillsHome()
+): Promise<string[]> {
+  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 installed: string[] = [];
+  for (const skill of skills) {
+    const target = skillInstallPath(skill, skillsHome);
+    await cp(skill.sourceDir, target, { recursive: true, force: true });
+    const skillMdPath = join(target, "SKILL.md");
+    const raw = await readFile(skillMdPath, "utf8");
+    const adjusted = prepareSkillMarkdownForCursorInstall(raw);
+    if (adjusted !== raw) {
+      await writeFile(skillMdPath, adjusted, "utf8");
+    }
+    installed.push(skill.leafDir);
+  }
+  return installed;
+}
+
+/** Drop monorepo `paths` globs 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 body = content.slice(match[0].length);
+  const adjustedBody = body.replace(
+    /\[`docs\/([^`]+)`\]\(\.\.\/\.\.\/docs\/[^)]+\)/g,
+    "docs/$1 in the @cursor/july package"
+  );
+  return `---\n${frontmatter.trimEnd()}\n---${adjustedBody}`;
+}
+
+function stripPathsFromFrontmatter(frontmatter: string): string {
+  const lines = frontmatter.split(/\r?\n/);
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (line.trimStart().startsWith("paths:")) {
+      i++;
+      while (i < lines.length && /^[ \t]*-/.test(lines[i] ?? "")) {
+        i++;
+      }
+      i--;
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\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>;
+  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.
+ */
+export async function offerInstallCursorSkills(
+  options: OfferInstallCursorSkillsOptions = {}
+): Promise<{ installed: string[]; skipped: boolean }> {
+  const out = options.out ?? ((text) => process.stdout.write(text));
+  const interactive =
+    options.interactive ??
+    (process.stdin.isTTY === true && process.stdout.isTTY === true);
+  const shipped = await listShippedPackageSkills(options.packageRoot);
+  if (shipped.length === 0) {
+    return { installed: [], skipped: true };
+  }
+
+  const home = options.skillsHome ?? cursorSkillsHome();
+  const targetDir = agentkitCursorSkillsDir(home);
+  const missing = await findMissingCursorSkills({
+    packageRoot: options.packageRoot,
+    skillsHome: home,
+  });
+  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) {
+    return { installed: [], skipped: true };
+  }
+
+  const c = stdoutPalette();
+  out(`${question}\n`);
+  out(c.dim(`  ${names}\n`));
+  if (missing.length < shipped.length) {
+    out(c.dim("  (overwrites existing copies with the package version)\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"));
+    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 };
+}
+
+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, "");
+}
+
+async function promptYesNo(
+  question: string,
+  options: {
+    defaultYes: boolean;
+    out: (text: string) => void;
+  }
+): Promise<boolean> {
+  const hint = options.defaultYes ? "Y/n" : "y/N";
+  options.out(`${question} [${hint}] `);
+  process.stdin.resume();
+  const line = await readOneLine(process.stdin);
+  process.stdin.pause();
+  if (line === undefined || line.trim() === "") {
+    return options.defaultYes;
+  }
+  const answer = line.trim().toLowerCase();
+  if (answer === "y" || answer === "yes") {
+    return true;
+  }
+  if (answer === "n" || answer === "no") {
+    return false;
+  }
+  return options.defaultYes;
+}
+
+function readOneLine(
+  stream: NodeJS.ReadableStream
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    let buffer = "";
+    const onData = (chunk: string | Buffer): void => {
+      buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      const newline = buffer.indexOf("\n");
+      if (newline === -1) {
+        return;
+      }
+      cleanup();
+      resolve(buffer.slice(0, newline).replace(/\r$/, ""));
+    };
+    const onEnd = (): void => {
+      cleanup();
+      resolve(buffer === "" ? undefined : buffer.replace(/\r$/, ""));
+    };
+    const cleanup = (): void => {
+      stream.off("data", onData);
+      stream.off("end", onEnd);
+    };
+    stream.on("data", onData);
+    stream.on("end", onEnd);
+  });
+}