fix(provider): respect explicit settingSources opt-out and harden rule writes

Address PR #56 review findings on the rules-channel system prompt:

- never force-append "project" to an explicitly configured settingSources
  (deliberate hardening opt-out); degrade to inline "message" delivery
  with a one-time warning instead
- wrap the rule write in try/catch: a failed write (read-only checkout)
  degrades to "message" mode for the turn rather than failing it
- add a generated-by sentinel to opencode.mdc frontmatter; a user-owned
  (sentinel-less) file is never overwritten or deleted
- thread one canonical cwd through the provider options and dispose so
  write and cleanup can't diverge and orphan the rule file
- make .cursor/rules/.gitignore ignore itself
- skip the rewrite when the rule content is unchanged (no sync fs write
  on the stream hot path)

Author: justin-carper

src/plugin/index.ts

@@ -39,6 +39,12 @@ export const CursorPlugin: Plugin = async (input) => {
 	// (reflecting mid-session enable/disable) rather than the startup snapshot.
 	const client = input?.client;
 	const directory = input?.directory;
+	// Canonical working directory for the generated system-prompt rule: the
+	// provider writes `.cursor/rules/opencode.mdc` under this path and dispose
+	// cleans it up from the same path. The config hook threads it into the
+	// provider options (respecting a user-configured `cwd` option) so write and
+	// cleanup can never diverge.
+	let resolvedCwd = directory ?? process.cwd();
 	let forwardMcp = true;
 	let userMcp: Record<string, McpServerConfig> = {};
 	// OAuth servers we've already warned about, so the toast fires once per
@@ -94,12 +100,21 @@ export const CursorPlugin: Plugin = async (input) => {
 				? { ...userMcp, ...translateMcpServers(config.mcp) }
 				: userMcp;
 
+			// One canonical cwd for the provider's rule write and our dispose
+			// cleanup: an explicit user option wins, else the plugin directory.
+			const optionCwd = existingOptions["cwd"];
+			resolvedCwd =
+				(typeof optionCwd === "string" ? optionCwd : undefined) ??
+				directory ??
+				process.cwd();
+
 			config.provider[PROVIDER_ID] = {
 				name: "Cursor",
 				npm: providerNpm(),
 				...existing,
 				options: {
 					...existingOptions,
+					cwd: resolvedCwd,
 					...(Object.keys(mcpServers).length > 0 ? { mcpServers } : {}),
 				},
 				models: { ...toOpencodeModels(models), ...(existing.models ?? {}) },
@@ -215,7 +230,9 @@ export const CursorPlugin: Plugin = async (input) => {
 		dispose: async () => {
 			// Best-effort: drop the generated system-prompt rule so it doesn't
 			// linger in the user's workspace / Cursor IDE after the session ends.
-			if (directory) removeSystemRule(directory);
+			// Uses the same canonical cwd the provider wrote to; sentinel-guarded,
+			// so a user-owned opencode.mdc is never deleted.
+			removeSystemRule(resolvedCwd);
 		},
 	};
 };

src/provider/language-model.ts

@@ -19,7 +19,7 @@ import {
 	promptToCursorMessage,
 	type SystemPromptMode,
 } from "./message-map.js";
-import { extractSystemText, writeSystemRule } from "./system-rule.js";
+import { extractSystemText, resolveSystemDelivery } from "./system-rule.js";
 import { streamAgentTurn, type CursorEvent } from "./agent-events.js";
 import {
 	cursorEventsToContent,
@@ -97,6 +97,15 @@ export class CursorLanguageModel implements LanguageModelV3 {
 		this.provider = config.providerName;
 	}
 
+	/** Messages already emitted, so degradation warnings fire once, not per turn. */
+	private readonly warned = new Set<string>();
+
+	private warnOnce(message: string): void {
+		if (this.warned.has(message)) return;
+		this.warned.add(message);
+		console.warn(`[${this.provider}] ${message}`);
+	}
+
 	private requireApiKey(): string {
 		const apiKey = resolveCursorApiKey(this.config.apiKey);
 		if (!apiKey) {
@@ -196,16 +205,18 @@ export class CursorLanguageModel implements LanguageModelV3 {
 
 		// In "rules" mode (default), deliver opencode's system prompt through
 		// Cursor's authoritative rules channel instead of the user transcript.
-		const systemMode: SystemPromptMode = this.config.systemPrompt ?? "rules";
-		let settingSources = this.config.settingSources;
-		if (systemMode === "rules") {
-			const systemText = extractSystemText(options.prompt);
-			if (writeSystemRule(this.config.cwd, systemText)) {
-				settingSources = settingSources?.includes("project")
-					? settingSources
-					: [...(settingSources ?? []), "project"];
-			}
-		}
+		// Degrades to inline "message" delivery when the user explicitly opted
+		// out of the "project" settings layer, when the rule file is user-owned,
+		// or when the write fails (read-only checkout etc.).
+		const delivery = resolveSystemDelivery({
+			mode: this.config.systemPrompt ?? "rules",
+			settingSources: this.config.settingSources,
+			cwd: this.config.cwd,
+			systemText: extractSystemText(options.prompt),
+			warn: (message) => this.warnOnce(message),
+		});
+		const systemMode: SystemPromptMode = delivery.mode;
+		const settingSources = delivery.settingSources;
 
 		const acquired = await acquireAgent({
 			apiKey: this.requireApiKey(),

src/provider/system-rule.ts

@@ -7,12 +7,21 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import type { LanguageModelV3Prompt } from "@ai-sdk/provider";
+import type { SettingSource } from "@cursor/sdk";
+import type { SystemPromptMode } from "./message-map.js";
 
 /** Location of the generated rule, relative to the agent's cwd. */
 const RULES_DIR = join(".cursor", "rules");
 const RULE_FILE = "opencode.mdc";
 const IGNORE_FILE = ".gitignore";
 
+/**
+ * Frontmatter sentinel marking the rule as generated by this plugin. Only
+ * files carrying it are ever overwritten or deleted, so a user-owned
+ * `.cursor/rules/opencode.mdc` is never clobbered.
+ */
+const SENTINEL = "generated: opencode-cursor";
+
 /** Concatenate every system-message body from an AI-SDK prompt (trimmed). */
 export function extractSystemText(prompt: LanguageModelV3Prompt): string {
 	const parts: string[] = [];
@@ -22,42 +31,135 @@ export function extractSystemText(prompt: LanguageModelV3Prompt): string {
 	return parts.join("\n\n").trim();
 }
 
+/** Outcome of a {@link writeSystemRule} attempt. */
+export type SystemRuleWrite =
+	/** Rule file created or updated. */
+	| "written"
+	/** Existing generated rule already has this content; write skipped. */
+	| "unchanged"
+	/** No system text to deliver; nothing written. */
+	| "empty"
+	/** A user-owned (sentinel-less) opencode.mdc exists; left untouched. */
+	| "blocked";
+
+/** True when the file carries the generated-by sentinel in its frontmatter. */
+function isGenerated(content: string): boolean {
+	if (!content.startsWith("---")) return false;
+	const end = content.indexOf("\n---", 3);
+	const frontmatter = end === -1 ? content : content.slice(0, end);
+	return frontmatter.split(/\r?\n/).includes(SENTINEL);
+}
+
 /**
  * Write opencode's system prompt to `<cwd>/.cursor/rules/opencode.mdc` as an
  * always-applied Cursor project rule. Cursor loads this through its authoritative
  * rules channel (`settingSources` including "project"), so opencode's controlling
  * instructions reach the agent without being flattened into the untrusted
- * user-message transcript (which injection-hardened models reject). Returns true
- * when a rule was written; a no-op (false) for empty text.
+ * user-message transcript (which injection-hardened models reject).
+ *
+ * The file carries a generated-by sentinel; a pre-existing sentinel-less file
+ * is treated as user-owned and never overwritten ("blocked"). An existing
+ * generated rule with identical content is left as-is ("unchanged") to keep
+ * sync fs writes off the stream hot path. May throw on fs errors (read-only
+ * checkout etc.) — callers should degrade gracefully.
  */
-export function writeSystemRule(cwd: string, systemText: string): boolean {
-	if (!systemText) return false;
+export function writeSystemRule(
+	cwd: string,
+	systemText: string,
+): SystemRuleWrite {
+	if (!systemText) return "empty";
 	const dir = join(cwd, RULES_DIR);
+	const path = join(dir, RULE_FILE);
+	const body = `---\nalwaysApply: true\n${SENTINEL}\n---\n\n${systemText}\n`;
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : undefined;
+	if (existing !== undefined) {
+		if (!isGenerated(existing)) return "blocked";
+		if (existing === body) return "unchanged";
+	}
 	mkdirSync(dir, { recursive: true });
-	writeFileSync(
-		join(dir, RULE_FILE),
-		`---\nalwaysApply: true\n---\n\n${systemText}\n`,
-		"utf8",
-	);
+	writeFileSync(path, body, "utf8");
 	ensureGitIgnored(dir);
-	return true;
+	return "written";
 }
 
-/** Keep the generated rule out of git via `.cursor/rules/.gitignore`. */
+/**
+ * Keep the generated rule out of git via `.cursor/rules/.gitignore` (which
+ * also ignores itself so it doesn't pollute `git status`).
+ */
 function ensureGitIgnored(dir: string): void {
 	const path = join(dir, IGNORE_FILE);
 	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-	if (existing.split(/\r?\n/).includes(RULE_FILE)) return;
+	const lines = existing.split(/\r?\n/);
+	const missing = [RULE_FILE, IGNORE_FILE].filter(
+		(entry) => !lines.includes(entry),
+	);
+	if (missing.length === 0) return;
 	const prefix =
 		existing && !existing.endsWith("\n") ? `${existing}\n` : existing;
-	writeFileSync(path, `${prefix}${RULE_FILE}\n`, "utf8");
+	writeFileSync(path, `${prefix}${missing.join("\n")}\n`, "utf8");
 }
 
-/** Remove the generated rule (best-effort); used on plugin dispose. */
+/**
+ * Remove the generated rule (best-effort); used on plugin dispose. Only
+ * deletes files carrying the generated-by sentinel — a user-owned
+ * opencode.mdc is left in place.
+ */
 export function removeSystemRule(cwd: string): void {
 	try {
-		rmSync(join(cwd, RULES_DIR, RULE_FILE));
+		const path = join(cwd, RULES_DIR, RULE_FILE);
+		if (isGenerated(readFileSync(path, "utf8"))) rmSync(path);
 	} catch {
 		// best effort — already gone or never written
 	}
 }
+
+/** How the system prompt will be delivered for this turn. */
+export interface SystemDelivery {
+	mode: SystemPromptMode;
+	settingSources: SettingSource[] | undefined;
+}
+
+/**
+ * Decide how opencode's system prompt reaches the Cursor agent for one turn.
+ *
+ * In "rules" mode this writes the rule file and enables the `project`
+ * settings layer — but ONLY when the user did not explicitly configure
+ * `settingSources` without "project" (a deliberate hardening opt-out: the
+ * project layer also loads the repo's `.cursor/mcp.json`, hooks, and other
+ * rules). On an opt-out, a failed write (read-only checkout etc.), or a
+ * user-owned rule file, it degrades to inline "message" delivery for the
+ * turn and reports the reason via `warn`. Never throws.
+ */
+export function resolveSystemDelivery(options: {
+	mode: SystemPromptMode;
+	settingSources: SettingSource[] | undefined;
+	cwd: string;
+	systemText: string;
+	warn: (message: string) => void;
+}): SystemDelivery {
+	const { mode, settingSources, cwd, systemText, warn } = options;
+	if (mode !== "rules") return { mode, settingSources };
+	if (settingSources && !settingSources.includes("project")) {
+		warn(
+			'systemPrompt "rules" needs the "project" settings layer, but settingSources was explicitly configured without it; delivering the system prompt inline ("message" mode) instead. Add "project" to settingSources or set systemPrompt: "message" to silence this.',
+		);
+		return { mode: "message", settingSources };
+	}
+	let result: SystemRuleWrite;
+	try {
+		result = writeSystemRule(cwd, systemText);
+	} catch (error) {
+		warn(
+			`failed to write .cursor/rules/${RULE_FILE} (${error instanceof Error ? error.message : String(error)}); delivering the system prompt inline ("message" mode) for this turn.`,
+		);
+		return { mode: "message", settingSources };
+	}
+	if (result === "blocked") {
+		warn(
+			`.cursor/rules/${RULE_FILE} exists but was not generated by opencode-cursor; leaving it untouched and delivering the system prompt inline ("message" mode).`,
+		);
+		return { mode: "message", settingSources };
+	}
+	if (result === "empty") return { mode, settingSources };
+	return { mode, settingSources: settingSources ?? ["project"] };
+}