@b-apm/integration-cursor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sdju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @b-apm/integration-cursor
+
+> **UNSTABLE:** Early public release. APIs and on-disk layouts may change without a major bump. Not production-ready.
+
+Minimal **Cursor** host for bapm (M5 polish + M9 MCP configure).
+
+## Detection vs forced target
+
+| Mode                           | When active                                                                    | Creates roots?                                                                                           |
+| ------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **Auto-detect**                | `.cursor/` **directory** **or** legacy `.cursorrules` **file** at project root | Only when materialize / configureMcp runs after a positive detect                                        |
+| **Forced** (`--target cursor`) | Explicit CLI/core forced target id, even if detect is false                    | MAY `mkdir` registered roots (`.cursor/`, `.agents/skills`, `.cursor/rules`, `.cursor/agents`) as needed |
+
+Auto-detect without force MUST NOT create `.cursor/` solely for MCP opt-in. Forced activation is owned by Install / CLI; this package’s `detect` stays an honest presence predicate.
+
+## Deploy roots (tg-002 / tg-003)
+
+Registered roots:
+
+- `.agents/skills` — skills → `<name>/SKILL.md`
+- `.cursor` — companion root (detection + rules/agents + MCP config)
+
+## Materialize routing
+
+| Primitive type | Destination                      |
+| -------------- | -------------------------------- |
+| skill          | `.agents/skills/<name>/SKILL.md` |
+| instruction    | `.cursor/rules/<name>.mdc`       |
+| agent          | `.cursor/agents/<name>.md`       |
+
+Thin copy/write from source content (minimal frontmatter only when content is missing). Writes are idempotent overwrites and never escape registered roots.
+
+**Skills / rules / agents materialize does not write `.cursor/mcp.json`.** MCP config is written only via the separate `configureMcp` path when install requests it.
+
+`materialize` returns a `MaterializeReport` (`deployedFiles: { path }[]`) via `@b-apm/integration-api` for lock inventory.
+
+## MCP configure (`configureMcp`)
+
+When install invokes `configureMcp` with eligible servers:
+
+- Writes / updates `.cursor/mcp.json` under the registered `.cursor/` root only
+- Shape: `{ "mcpServers": { "<name>": { "command"|"url"|… } } }` (stdio / http)
+- Idempotent overwrite of bapm-owned server keys (keyed by server name); unknown user keys are preserved when present
+- Returns a `ConfigureMcpReport` (`configPath`, `servers`, `deployedFiles`) for lock `mcp_*` inventory
+
+## Dependencies
+
+Depends only on `@b-apm/integration-api` among bapm packages — not `@b-apm/core`.
+Shared materialize helpers (`sanitizeName`, `assertUnderDeployRoots`, `readPrimitiveContent`, …) come from `@b-apm/integration-api`; this package keeps Cursor detect and path routing only.
+Register via `createIntegrationRegistry().register(createCursorIntegration())` in CLI or tests.
+
+Third-party authors publishing a custom host for object-map `targets` should prefer a named `createIntegration` factory (see `@b-apm/integration-api` README — loadable export contract). This package’s `createCursorIntegration` remains the Cursor-specific factory accepted by the CLI loader.

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import { BapmIntegration } from "@b-apm/integration-api";
+//#region src/createCursorIntegration.d.ts
+/**
+ * Create the Cursor target.
+ * Detect: `.cursor/` directory **or** legacy `.cursorrules` file.
+ * Materialize: skills → `.agents/skills/<name>/SKILL.md`,
+ * instructions → `.cursor/rules/<name>.mdc`,
+ * agents → `.cursor/agents/<name>.md`,
+ * commands → `.cursor/commands/<name>.md`,
+ * hooks → merge `.cursor/hooks.json` (+ script copy under `.cursor/hooks/`).
+ * MCP: optional `configureMcp` writes `.cursor/mcp.json` (not via materialize).
+ */
+declare function createCursorIntegration(options?: {
+  id?: string;
+  deployRoots?: string[];
+}): BapmIntegration;
+//#endregion
+export { createCursorIntegration };

package/dist/index.mjs

@@ -0,0 +1,366 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { SHARED_COMMAND_FRONTMATTER_KEYS, assertUnderDeployRoots, compileMarkdownReport, copyHookScript, filterFrontmatterKeys, materializeSkill, primitivesList, primitivesMaterialize, readHookOwnershipSidecar, readPrimitiveContent, renderPrimitivesMarkdown, sanitizeName, stripOwnedHookCommands, writeDeployedFile, writeHookOwnershipSidecar } from "@b-apm/integration-api";
+//#region src/createCursorIntegration.ts
+const DEFAULT_DEPLOY_ROOTS = [".agents/skills", ".cursor"];
+const MCP_JSON_REL = ".cursor/mcp.json";
+const HOOKS_JSON_REL = ".cursor/hooks.json";
+const HOOKS_OWNERSHIP_REL = ".cursor/bapm-hooks.json";
+/**
+* Create the Cursor target.
+* Detect: `.cursor/` directory **or** legacy `.cursorrules` file.
+* Materialize: skills → `.agents/skills/<name>/SKILL.md`,
+* instructions → `.cursor/rules/<name>.mdc`,
+* agents → `.cursor/agents/<name>.md`,
+* commands → `.cursor/commands/<name>.md`,
+* hooks → merge `.cursor/hooks.json` (+ script copy under `.cursor/hooks/`).
+* MCP: optional `configureMcp` writes `.cursor/mcp.json` (not via materialize).
+*/
+function createCursorIntegration(options) {
+	const id = options?.id ?? "cursor";
+	const deployRoots = [...options?.deployRoots ?? DEFAULT_DEPLOY_ROOTS];
+	return {
+		id,
+		deployRoots,
+		detect: ({ cwd }) => {
+			const cursorDir = join(cwd, ".cursor");
+			if (existsSync(cursorDir) && statSync(cursorDir).isDirectory()) return true;
+			const legacy = join(cwd, ".cursorrules");
+			return existsSync(legacy) && statSync(legacy).isFile();
+		},
+		getDeployRoots: () => [...deployRoots],
+		async compile(primitives, context) {
+			const content = renderPrimitivesMarkdown({
+				primitives: primitivesList(primitives),
+				title: "# AGENTS.md"
+			});
+			return compileMarkdownReport({
+				cwd: context.cwd,
+				outputFile: context.outputFile ?? "AGENTS.md",
+				write: context.write,
+				content,
+				outsideCwdMessage: "Cursor compile output must be a cwd-relative file path"
+			});
+		},
+		async materialize(primitives, ctx) {
+			const cwd = resolve(ctx?.cwd ?? process.cwd());
+			const roots = ctx?.deployRoots?.length ? [...ctx.deployRoots] : deployRoots;
+			if (!roots.some((r) => r === ".agents/skills" || r.startsWith(".agents/skills"))) throw new Error("cursor target missing .agents/skills deploy root");
+			if (!roots.some((r) => r === ".cursor" || r.startsWith(".cursor"))) throw new Error("cursor target missing .cursor deploy root");
+			const deployedFiles = [];
+			const diagnostics = [];
+			const hookPrimitives = [];
+			await primitivesMaterialize(primitives, {
+				skill(p, { name }) {
+					deployedFiles.push(...materializeSkill({
+						primitive: p,
+						cwd,
+						deployRoots: roots,
+						destDir: join(".agents", "skills", name)
+					}));
+				},
+				instruction(p, { name }) {
+					deployedFiles.push(writeDeployedFile({
+						cwd,
+						deployRoots: roots,
+						destRel: join(".cursor", "rules", `${name}.mdc`),
+						content: readPrimitiveContent(p),
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					}));
+				},
+				agent(p, { name }) {
+					deployedFiles.push(writeDeployedFile({
+						cwd,
+						deployRoots: roots,
+						destRel: join(".cursor", "agents", `${name}.md`),
+						content: readPrimitiveContent(p),
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					}));
+				},
+				command(p, { name }) {
+					const { content, droppedKeys } = filterFrontmatterKeys(readPrimitiveContent(p), SHARED_COMMAND_FRONTMATTER_KEYS);
+					deployedFiles.push(writeDeployedFile({
+						cwd,
+						deployRoots: roots,
+						destRel: join(".cursor", "commands", `${name}.md`),
+						content,
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					}));
+					if (droppedKeys.length > 0) diagnostics.push({
+						code: "CURSOR_COMMAND_FRONTMATTER_DROPPED",
+						message: `Dropped non-preserved command frontmatter keys for "${p.name}": ${droppedKeys.join(", ")}`,
+						primitive: String(p.name),
+						droppedKeys
+					});
+				},
+				hook(p) {
+					hookPrimitives.push(p);
+				}
+			});
+			if (hookPrimitives.length > 0) {
+				const hookDeployed = materializeCursorHooks({
+					cwd,
+					roots,
+					hooks: hookPrimitives
+				});
+				deployedFiles.push(...hookDeployed.deployedFiles);
+				diagnostics.push(...hookDeployed.diagnostics);
+			}
+			return {
+				targetId: id,
+				deployedFiles,
+				...diagnostics.length > 0 ? { diagnostics } : {}
+			};
+		},
+		async configureMcp(servers, ctx) {
+			return writeCursorMcpConfig(servers, {
+				cwd: resolve(ctx?.cwd ?? process.cwd()),
+				deployRoots: ctx?.deployRoots?.length ? [...ctx.deployRoots] : deployRoots,
+				targetId: ctx?.targetId ?? id
+			});
+		}
+	};
+}
+function writeCursorMcpConfig(servers, ctx) {
+	const { cwd, deployRoots } = ctx;
+	if (!deployRoots.some((r) => r === ".cursor" || r.startsWith(".cursor"))) throw new Error("cursor configureMcp requires a registered .cursor deploy root");
+	const destFile = join(cwd, ".cursor", "mcp.json");
+	assertUnderDeployRoots(cwd, destFile, deployRoots);
+	mkdirSync(join(cwd, ".cursor"), { recursive: true });
+	const existing = readExistingMcpServers(destFile);
+	const { entries: incoming, diagnostics } = normalizeServerEntries(servers);
+	const next = { ...existing };
+	const writtenNames = [];
+	for (const [name, entry] of Object.entries(incoming)) {
+		next[name] = entry;
+		writtenNames.push(name);
+	}
+	writeFileSync(destFile, `${JSON.stringify({ mcpServers: next }, null, 2)}\n`, "utf8");
+	return {
+		targetId: ctx.targetId,
+		configPath: MCP_JSON_REL,
+		servers: writtenNames,
+		deployedFiles: [{ path: MCP_JSON_REL }],
+		diagnostics
+	};
+}
+function readExistingMcpServers(path) {
+	if (!existsSync(path)) return {};
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		return raw.mcpServers && typeof raw.mcpServers === "object" ? { ...raw.mcpServers } : {};
+	} catch {
+		return {};
+	}
+}
+function normalizeServerEntries(servers) {
+	const out = {};
+	const diagnostics = [];
+	const list = Array.isArray(servers) ? servers : Object.entries(servers).map(([name, value]) => ({
+		...value,
+		name: value.name ?? name
+	}));
+	for (const server of list) {
+		const name = String(server.name ?? "").trim();
+		if (!name) continue;
+		const entry = toCursorServerEntry(server);
+		if (!entry) {
+			diagnostics.push({
+				code: "CURSOR_PORTABLE_MCP_UNSUPPORTED",
+				message: `Cursor cannot faithfully represent portable MCP server "${name}"`,
+				server: name
+			});
+			continue;
+		}
+		out[name] = entry;
+	}
+	return {
+		entries: out,
+		diagnostics
+	};
+}
+function toCursorServerEntry(server) {
+	const transport = String(server.transport ?? server.type ?? "").toLowerCase();
+	const entry = {};
+	if (server.format === "agent-plugin") {
+		if (transport === "stdio") {
+			if (typeof server.command !== "string") return void 0;
+			entry.command = server.command;
+			if (Array.isArray(server.args)) entry.args = server.args;
+			if (typeof server.cwd === "string") entry.cwd = server.cwd;
+			entry.type = "stdio";
+		} else if (transport === "streamable-http" || transport === "sse") {
+			if (typeof server.url !== "string") return void 0;
+			entry.url = server.url;
+			entry.type = transport === "streamable-http" ? "http" : "sse";
+		} else return;
+		if (server.env && typeof server.env === "object") entry.env = server.env;
+		return entry;
+	}
+	if (transport === "http" || transport === "sse" || typeof server.url === "string") {
+		if (server.url) entry.url = server.url;
+		if (transport) entry.type = transport === "sse" ? "sse" : "http";
+	} else {
+		if (server.command) entry.command = server.command;
+		if (Array.isArray(server.args)) entry.args = server.args;
+		entry.type = "stdio";
+	}
+	if (server.env && typeof server.env === "object") entry.env = server.env;
+	for (const [key, value] of Object.entries(server)) {
+		if ([
+			"name",
+			"transport",
+			"type",
+			"command",
+			"args",
+			"url",
+			"env",
+			"packageName",
+			"registry",
+			"format",
+			"cwd"
+		].includes(key)) continue;
+		if (value !== void 0) entry[key] = value;
+	}
+	return entry;
+}
+function materializeCursorHooks(args) {
+	const { cwd, roots, hooks } = args;
+	const deployedFiles = [];
+	const diagnostics = [];
+	const hooksPath = join(cwd, HOOKS_JSON_REL);
+	const ownershipPath = join(cwd, HOOKS_OWNERSHIP_REL);
+	assertUnderDeployRoots(cwd, hooksPath, roots);
+	assertUnderDeployRoots(cwd, ownershipPath, roots);
+	mkdirSync(join(cwd, ".cursor"), { recursive: true });
+	const doc = readHooksDoc(hooksPath);
+	const ownership = readHookOwnershipSidecar(ownershipPath);
+	if (doc.hooks && typeof doc.hooks === "object") stripOwnedHookCommands(doc.hooks, ownership);
+	const nextOwned = {};
+	for (const p of hooks) {
+		const name = sanitizeName(String(p.name));
+		const srcPath = p.path ? resolve(p.path) : void 0;
+		if (!srcPath || !existsSync(srcPath) || !statSync(srcPath).isFile()) {
+			diagnostics.push({
+				code: "CURSOR_HOOK_SOURCE_MISSING",
+				message: `Hook primitive "${p.name}" has no readable source JSON`,
+				primitive: String(p.name)
+			});
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(srcPath, "utf8"));
+		} catch (cause) {
+			diagnostics.push({
+				code: "CURSOR_HOOK_JSON_INVALID",
+				message: `Hook "${p.name}" JSON is invalid: ${cause instanceof Error ? cause.message : String(cause)}`,
+				primitive: String(p.name)
+			});
+			continue;
+		}
+		const sourceHooks = parsed.hooks && typeof parsed.hooks === "object" ? parsed.hooks : {};
+		const ownedEntries = [];
+		const scripts = [];
+		if (!doc.hooks || typeof doc.hooks !== "object") doc.hooks = {};
+		if (typeof parsed.version === "number" && doc.version === void 0) doc.version = parsed.version;
+		for (const [event, entries] of Object.entries(sourceHooks)) {
+			if (!Array.isArray(entries)) continue;
+			const destList = Array.isArray(doc.hooks[event]) ? [...doc.hooks[event]] : [];
+			for (const entry of entries) {
+				if (!entry || typeof entry !== "object") continue;
+				const command = typeof entry.command === "string" ? entry.command.trim() : "";
+				if (!command) {
+					destList.push({ ...entry });
+					continue;
+				}
+				const rewritten = copyHookScript({
+					cwd,
+					deployRoots: roots,
+					hookFile: srcPath,
+					command,
+					alreadyDeployedNeedle: ".cursor/",
+					destRel: `.cursor/hooks/${name}/${basename(command.replace(/^\.\//, ""))}`,
+					commandAsDotSlash: true
+				});
+				const nextEntry = {
+					...entry,
+					command: rewritten.commandRel
+				};
+				destList.push(nextEntry);
+				ownedEntries.push({
+					event,
+					command: rewritten.commandRel
+				});
+				if (rewritten.scriptRel) {
+					scripts.push(rewritten.scriptRel);
+					deployedFiles.push({
+						path: rewritten.scriptRel,
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					});
+				}
+			}
+			doc.hooks[event] = destList;
+		}
+		nextOwned[name] = {
+			...p.packageName ? { packageName: p.packageName } : {},
+			entries: ownedEntries,
+			scripts
+		};
+	}
+	if (doc.version === void 0) doc.version = 1;
+	writeFileSync(hooksPath, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+	writeHookOwnershipSidecar(ownershipPath, { owned: nextOwned });
+	deployedFiles.push({
+		path: HOOKS_JSON_REL,
+		...hooks[0] ? { primitive: {
+			name: String(hooks[0].name),
+			packageName: hooks[0].packageName
+		} } : {}
+	});
+	deployedFiles.push({
+		path: HOOKS_OWNERSHIP_REL,
+		...hooks[0] ? { primitive: {
+			name: String(hooks[0].name),
+			packageName: hooks[0].packageName
+		} } : {}
+	});
+	return {
+		deployedFiles,
+		diagnostics
+	};
+}
+function readHooksDoc(path) {
+	if (!existsSync(path)) return {
+		version: 1,
+		hooks: {}
+	};
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (!raw || typeof raw !== "object") return {
+			version: 1,
+			hooks: {}
+		};
+		if (!raw.hooks || typeof raw.hooks !== "object") raw.hooks = {};
+		return raw;
+	} catch {
+		return {
+			version: 1,
+			hooks: {}
+		};
+	}
+}
+//#endregion
+export { createCursorIntegration };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@b-apm/integration-cursor",
+  "version": "0.1.0",
+  "description": "Cursor integration for bapm",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@b-apm/integration-api": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sdju/bapm.git",
+    "directory": "packages/integration-cursor"
+  },
+  "homepage": "https://github.com/Sdju/bapm#readme",
+  "bugs": {
+    "url": "https://github.com/Sdju/bapm/issues"
+  },
+  "keywords": [
+    "unstable",
+    "bapm",
+    "b-apm"
+  ],
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}