cursor-rules-to-github-copilot 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# cursor-rules-to-github-copilot
+
+CLI that reads **Cursor** rules from `.cursor/rules` (`*.mdc` / `*.md`) and generates **GitHub Copilot** instruction files for **VS Code**:
+
+| Cursor | Generated |
+|--------|-----------|
+| `alwaysApply: true` | `.github/copilot-instructions.md` (sections per rule) |
+| `globs: ...` | `.github/instructions/*.instructions.md` with `applyTo` |
+| No globs, not always | `.instructions.md` without `applyTo` (attach manually in chat) |
+
+Copilot does not read `.cursor/rules` directly; run this tool after you change Cursor rules.
+
+## Usage
+
+```bash
+npx cursor-rules-to-github-copilot
+```
+
+From another directory:
+
+```bash
+npx cursor-rules-to-github-copilot --cwd /path/to/repo
+```
+
+Options:
+
+- `--cwd <dir>` — workspace root (default: current directory)
+- `--rules-dir <rel>` — rules folder relative to cwd (default: `.cursor/rules`)
+- `--dry-run` — show what would be written
+- `--no-banner` — omit HTML comment banners in generated files
+
+## npm script (optional)
+
+```json
+{
+  "scripts": {
+    "sync:copilot": "cursor-rules-to-github-copilot"
+  }
+}
+```
+
+Generated files under `.github/instructions/` are not pruned automatically. If you delete or rename a Cursor rule, remove the old `*.instructions.md` files yourself (or delete the folder and run the CLI again).
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { convert } = require("../lib/convert");
+
+function printHelp() {
+  console.log(`cursor-rules-to-github-copilot — Cursor .cursor/rules → GitHub Copilot instructions
+
+Usage:
+  npx cursor-rules-to-github-copilot [options]
+
+Options:
+  --cwd <dir>       Workspace root (default: current directory)
+  --rules-dir <rel> Rules directory relative to cwd (default: .cursor/rules)
+  --dry-run         Print actions without writing files
+  --no-banner       Omit generator banner comments in output files
+  -h, --help        Show help
+
+Outputs:
+  .github/copilot-instructions.md     — rules with alwaysApply: true
+  .github/instructions/*.instructions.md — globs → applyTo, or no applyTo if no globs
+`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("-h") || argv.includes("--help")) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const opts = {
+    root: process.cwd(),
+    rulesDir: undefined,
+    dryRun: argv.includes("--dry-run"),
+    noBanner: argv.includes("--no-banner"),
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") {
+      opts.root = path.resolve(argv[++i] || "");
+      if (!argv[i]) {
+        console.error("cursor-rules-to-github-copilot: --cwd requires a path");
+        process.exit(1);
+      }
+    } else if (a === "--rules-dir") {
+      opts.rulesDir = argv[++i];
+      if (!opts.rulesDir) {
+        console.error("cursor-rules-to-github-copilot: --rules-dir requires a path");
+        process.exit(1);
+      }
+    }
+  }
+
+  try {
+    const result = await convert(opts);
+    console.log(result.message);
+    if (result.dryRun) {
+      for (const w of result.scopedWrites) {
+        console.log("  write:", path.relative(opts.root, w.dest));
+      }
+      if (result.alwaysPath) {
+        console.log("  write:", path.relative(opts.root, result.alwaysPath));
+      }
+    }
+  } catch (e) {
+    console.error("cursor-rules-to-github-copilot:", e.message || e);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/convert.js

@@ -0,0 +1,222 @@
+"use strict";
+
+const fs = require("fs/promises");
+const path = require("path");
+const matter = require("gray-matter");
+
+const DEFAULT_RULES_DIR = ".cursor/rules";
+const OUT_INSTRUCTIONS = ".github/instructions";
+const OUT_ALWAYS = ".github/copilot-instructions.md";
+
+const BANNER = `<!-- Generated by cursor-rules-to-github-copilot — re-run after changing Cursor rules. -->\n\n`;
+
+/**
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function walkFiles(dir) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (e) {
+    if (e && e.code === "ENOENT") return [];
+    throw e;
+  }
+  const out = [];
+  for (const ent of entries) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...(await walkFiles(full)));
+    } else if (ent.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {unknown} v
+ * @returns {string[]}
+ */
+function normalizeGlobs(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) {
+    return v.map(String).map((s) => s.trim()).filter(Boolean);
+  }
+  const s = String(v).trim();
+  if (!s) return [];
+  return [s];
+}
+
+/**
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function isAlwaysApply(v) {
+  if (v === true) return true;
+  if (v === false || v == null) return false;
+  if (typeof v === "string") {
+    const t = v.trim().toLowerCase();
+    return t === "true" || t === "yes" || t === "1";
+  }
+  return Boolean(v);
+}
+
+/**
+ * Stable slug from rules-relative path for filenames.
+ * @param {string} rel - posix-style relative path without leading ./
+ */
+function slugFromRel(rel) {
+  const noExt = rel.replace(/\.(mdc|md)$/i, "");
+  return noExt.replace(/\\/g, "/").replace(/\//g, "-");
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.root - workspace root
+ * @param {string} [opts.rulesDir]
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.noBanner]
+ */
+async function convert(opts) {
+  const root = path.resolve(opts.root);
+  const rulesDir = path.join(root, opts.rulesDir || DEFAULT_RULES_DIR);
+  const dryRun = Boolean(opts.dryRun);
+  const noBanner = Boolean(opts.noBanner);
+
+  const allFiles = await walkFiles(rulesDir);
+  const ruleFiles = allFiles
+    .filter((f) => /\.(mdc|md)$/i.test(f))
+    .sort((a, b) => a.localeCompare(b));
+
+  if (ruleFiles.length === 0) {
+    return {
+      ok: true,
+      message: `No rule files found under ${path.relative(root, rulesDir) || "."}`,
+      alwaysParts: [],
+      scopedWrites: [],
+      dryRun,
+    };
+  }
+
+  /** @type {{ source: string, body: string, description?: string }[]} */
+  const alwaysParts = [];
+  /** @type {{ dest: string, content: string }[]} */
+  const scopedWrites = [];
+
+  for (const abs of ruleFiles) {
+    const raw = await fs.readFile(abs, "utf8");
+    const parsed = matter(raw);
+    const data = parsed.data || {};
+    const rel = path.relative(rulesDir, abs).split(path.sep).join("/");
+    const slug = slugFromRel(rel);
+    const description =
+      typeof data.description === "string" ? data.description.trim() : "";
+    const globs = normalizeGlobs(data.globs);
+    const always = isAlwaysApply(data.alwaysApply);
+
+    const header = `<!-- Source: ${DEFAULT_RULES_DIR}/${rel} -->\n`;
+
+    if (always) {
+      let block = header;
+      if (description) {
+        block += `> ${description.replace(/\n/g, "\n> ")}\n\n`;
+      }
+      block += parsed.content.trim() ? `${parsed.content.trim()}\n\n` : "";
+      alwaysParts.push({
+        source: `${DEFAULT_RULES_DIR}/${rel}`,
+        body: block,
+        description,
+      });
+      continue;
+    }
+
+    if (globs.length === 0) {
+      // Cursor "intelligent" / manual: emit instructions file without applyTo (attach manually in VS Code).
+      const name = `${slug}.instructions.md`;
+      const dest = path.join(root, OUT_INSTRUCTIONS, name);
+      const fm = [
+        "---",
+        description ? `description: ${JSON.stringify(description)}` : null,
+        `name: ${JSON.stringify(slug)}`,
+        "---",
+        "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+      const content = (noBanner ? "" : BANNER) + fm + "\n" + header + (parsed.content.trim() || "(empty rule body)") + "\n";
+      scopedWrites.push({ dest, content });
+      continue;
+    }
+
+    globs.forEach((g, i) => {
+      const suffix = globs.length > 1 ? `-${i + 1}` : "";
+      const name = `${slug}${suffix}.instructions.md`;
+      const dest = path.join(root, OUT_INSTRUCTIONS, name);
+      const fm = [
+        "---",
+        `name: ${JSON.stringify(`${slug}${suffix}`)}`,
+        description ? `description: ${JSON.stringify(description)}` : null,
+        `applyTo: ${JSON.stringify(g)}`,
+        "---",
+        "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+      const content =
+        (noBanner ? "" : BANNER) +
+        fm +
+        "\n" +
+        header +
+        (parsed.content.trim() || "(empty rule body)") +
+        "\n";
+      scopedWrites.push({ dest, content });
+    });
+  }
+
+  let alwaysDoc = "";
+  if (alwaysParts.length > 0) {
+    alwaysDoc =
+      (noBanner ? "" : BANNER) +
+      "# Project instructions (from Cursor rules)\n\n" +
+      alwaysParts
+        .map(
+          (p) =>
+            `## ${p.source}\n\n${p.body.trim()}\n`
+        )
+        .join("\n");
+  }
+
+  if (!dryRun) {
+    const outInst = path.join(root, OUT_INSTRUCTIONS);
+    await fs.mkdir(outInst, { recursive: true });
+    await fs.mkdir(path.join(root, ".github"), { recursive: true });
+
+    for (const { dest, content } of scopedWrites) {
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.writeFile(dest, content, "utf8");
+    }
+
+    const alwaysPath = path.join(root, OUT_ALWAYS);
+    if (alwaysDoc) {
+      await fs.writeFile(alwaysPath, alwaysDoc, "utf8");
+    } else {
+      try {
+        await fs.unlink(alwaysPath);
+      } catch (e) {
+        if (e && e.code !== "ENOENT") throw e;
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    message: `Processed ${ruleFiles.length} rule file(s).`,
+    alwaysParts,
+    scopedWrites,
+    alwaysPath: alwaysDoc ? path.join(root, OUT_ALWAYS) : null,
+    dryRun,
+  };
+}
+
+module.exports = { convert, walkFiles, DEFAULT_RULES_DIR, OUT_ALWAYS, OUT_INSTRUCTIONS };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cursor-rules-to-github-copilot",
+  "version": "0.1.0",
+  "description": "Convert Cursor .cursor/rules (*.mdc) to GitHub Copilot instruction files for VS Code",
+  "license": "MIT",
+  "author": "",
+  "keywords": [
+    "cursor",
+    "github-copilot",
+    "vscode",
+    "rules",
+    "copilot-instructions"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "cursor-rules-to-github-copilot": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}