fix(*): address review feedback on Clerk agent rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: royanger

packages/expo/app.plugin.js

@@ -7,6 +7,7 @@
  * 3. If @clerk/expo-native-components is installed, its config plugin is applied for the Clerk native SDKs
  */
 const { AndroidConfig, withAndroidManifest, withEntitlementsPlist, withInfoPlist } = require('@expo/config-plugins');
+const { isAgentEnvironment, isAutomatedEnvironment, isProductionEnvironment } = require('@clerk/shared/utils');
 
 const fs = require('fs');
 const path = require('path');
@@ -15,43 +16,8 @@ const CLERK_EXPO_NATIVE = '@clerk/expo-native-components';
 const CLERK_EXPO_NATIVE_OPTIONS = ['keychainService', 'theme'];
 let didWriteAgentRules = false;
 
-const isTruthyEnvValue = value => typeof value === 'string' && !!value && !['0', 'false', 'off', 'no'].includes(value);
-
-const isAgentEnvironment = () =>
-  [
-    'CLAUDECODE',
-    'CURSOR_AGENT',
-    'CURSOR_CLI',
-    'CURSOR_EXTENSION_HOST_ROLE',
-    'CURSOR_TRACE_ID',
-    'GITHUB_COPILOT_AGENT',
-    'GITHUB_COPILOT_CHAT',
-    'AGENT',
-    'AGENTS',
-  ].some(name => isTruthyEnvValue(process.env[name]));
-
-const isAutomatedEnvironment = () =>
-  [
-    'CI',
-    'CONTINUOUS_INTEGRATION',
-    'GITHUB_ACTIONS',
-    'GITLAB_CI',
-    'CIRCLECI',
-    'TRAVIS',
-    'BUILDKITE',
-    'BITBUCKET_BUILD_NUMBER',
-    'APPVEYOR',
-    'CODEBUILD_BUILD_ID',
-    'TF_BUILD',
-    'TEAMCITY_VERSION',
-    'JENKINS_URL',
-    'HUDSON_URL',
-    'BAMBOO_BUILDKEY',
-    'CF_PAGES',
-  ].some(name => isTruthyEnvValue(process.env[name]));
-
 const maybeWriteAgentRules = config => {
-  if (didWriteAgentRules || isAutomatedEnvironment() || !isAgentEnvironment()) {
+  if (didWriteAgentRules || isProductionEnvironment() || isAutomatedEnvironment() || !isAgentEnvironment()) {
     return;
   }
 
@@ -211,6 +177,7 @@ const withClerkExpo = (config, props = {}) => {
 module.exports = withClerkExpo;
 module.exports._testing = {
   addHostedAuthIntentFilter,
+  maybeWriteAgentRules,
   withClerkExpoNativeComponents,
   withClerkFaceIDPermission,
 };

packages/expo/src/__tests__/appPlugin.agentRules.test.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+
+import { agentEnvironmentVariables, automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+const nodeRequire = createRequire(import.meta.url);
+const pluginPath = nodeRequire.resolve('../../app.plugin.js');
+
+const loadMaybeWriteAgentRules = () => {
+  delete nodeRequire.cache[pluginPath];
+  return nodeRequire(pluginPath)._testing.maybeWriteAgentRules;
+};
+
+describe('maybeWriteAgentRules', () => {
+  let projectRoot;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'clerk-expo-agent-rules-'));
+    fs.writeFileSync(path.join(projectRoot, 'package.json'), '{}');
+    for (const name of [...agentEnvironmentVariables, ...automatedEnvironmentVariables]) {
+      vi.stubEnv(name, '');
+    }
+    vi.stubEnv('NODE_ENV', 'development');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  const agentsMdPath = () => path.join(projectRoot, 'AGENTS.md');
+  const config = () => ({ _internal: { projectRoot } });
+
+  test('writes the Expo rules once per process under an AI agent', () => {
+    vi.stubEnv('CLAUDECODE', '1');
+    const maybeWriteAgentRules = loadMaybeWriteAgentRules();
+
+    maybeWriteAgentRules(config());
+    expect(fs.readFileSync(agentsMdPath(), 'utf8')).toContain('<!-- BEGIN:clerk-agent-rules:expo -->');
+
+    fs.rmSync(agentsMdPath());
+    maybeWriteAgentRules(config());
+    expect(fs.existsSync(agentsMdPath())).toBe(false);
+  });
+
+  test('skips when the agent variable is set to a false value', () => {
+    vi.stubEnv('CLAUDECODE', 'False');
+
+    loadMaybeWriteAgentRules()(config());
+
+    expect(fs.existsSync(agentsMdPath())).toBe(false);
+  });
+
+  test('skips in production', () => {
+    vi.stubEnv('CLAUDECODE', '1');
+    vi.stubEnv('NODE_ENV', 'production');
+
+    loadMaybeWriteAgentRules()(config());
+
+    expect(fs.existsSync(agentsMdPath())).toBe(false);
+  });
+
+  test('skips in CI', () => {
+    vi.stubEnv('CLAUDECODE', '1');
+    vi.stubEnv('CI', 'true');
+
+    loadMaybeWriteAgentRules()(config());
+
+    expect(fs.existsSync(agentsMdPath())).toBe(false);
+  });
+});

packages/shared/src/__tests__/agentRules.spec.ts

@@ -120,6 +120,36 @@ describe('writeClerkAgentRules', () => {
   });
 });
 
+describe('writeClerkAgentRules with an unmatched BEGIN marker', () => {
+  it('keeps text after an orphan shared BEGIN marker across runs', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Team rules\n\n<!-- BEGIN:clerk-agent-rules -->\nold\n\n## My notes\nKeep this.\n',
+    });
+
+    for (let run = 0; run < 2; run++) {
+      writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+      const content = memory.read('/repo/AGENTS.md');
+      expect(content).toContain('Keep this.');
+      expect(content?.match(/<!-- BEGIN:clerk-agent-rules -->/g)).toHaveLength(1);
+    }
+  });
+
+  it('keeps text after an orphan SDK BEGIN marker across runs', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': '<!-- BEGIN:clerk-agent-rules:nextjs -->\nold\n\n## My notes\nKeep this.\n',
+    });
+
+    for (let run = 0; run < 2; run++) {
+      writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+      const content = memory.read('/repo/AGENTS.md');
+      expect(content).toContain('Keep this.');
+      expect(content?.match(/<!-- BEGIN:clerk-agent-rules:nextjs -->/g)).toHaveLength(1);
+    }
+  });
+});
+
 describe('writeClerkAgentRules with an existing CLAUDE.md', () => {
   it('adds an @AGENTS.md import when CLAUDE.md does not load AGENTS.md', () => {
     const memory = createMemoryFs({

packages/shared/src/__tests__/runtimeEnvironment.spec.ts

@@ -95,3 +95,35 @@ describe('isAgentEnvironment', () => {
     expect(isAgentEnvironment()).toBe(false);
   });
 });
+
+describe('isAgentEnvironment with Cursor', () => {
+  beforeEach(() => {
+    agentEnvironmentVariables.forEach(name => {
+      vi.stubEnv(name, undefined);
+      vi.stubGlobal(name, undefined);
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+  });
+
+  it('returns true when CURSOR_EXTENSION_HOST_ROLE is agent-exec', () => {
+    vi.stubEnv('CURSOR_EXTENSION_HOST_ROLE', 'agent-exec');
+
+    expect(isAgentEnvironment()).toBe(true);
+  });
+
+  it('returns false for any other CURSOR_EXTENSION_HOST_ROLE value', () => {
+    vi.stubEnv('CURSOR_EXTENSION_HOST_ROLE', 'user');
+
+    expect(isAgentEnvironment()).toBe(false);
+  });
+
+  it('returns true when CURSOR_TRACE_ID is set', () => {
+    vi.stubEnv('CURSOR_TRACE_ID', 'abc123');
+
+    expect(isAgentEnvironment()).toBe(true);
+  });
+});

packages/shared/src/agentRules/index.ts

@@ -166,6 +166,10 @@ function upsertMarkedBlock(
     return content.slice(0, startIndex) + block + content.slice(endIndex + end.length);
   }
 
+  if (startIndex !== -1) {
+    return content;
+  }
+
   if (insertAfter) {
     const insertIndex = content.indexOf(insertAfter);
     if (insertIndex !== -1) {

packages/shared/src/utils/runtimeEnvironment.ts

@@ -75,5 +75,8 @@ export const isAutomatedEnvironment = (): boolean => {
 };
 
 export const isAgentEnvironment = (): boolean => {
-  return agentEnvironmentVariables.some(name => isTruthyEnvValue(getEnvVariable(name)));
+  return agentEnvironmentVariables.some(name => {
+    const value = getEnvVariable(name);
+    return name === 'CURSOR_EXTENSION_HOST_ROLE' ? value === 'agent-exec' : isTruthyEnvValue(value);
+  });
 };

packages/upgrade/src/__tests__/integration/agent-rules.test.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { detectClerkAgentRuleSdks } from '../../util/agent-rules.js';
+
+describe('detectClerkAgentRuleSdks', () => {
+  let root;
+
+  const writePackage = (dir, pkg) => {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg));
+  };
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'clerk-upgrade-agent-rules-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('includes SDKs declared in the workspace root package.json', () => {
+    writePackage(root, { name: 'app', workspaces: ['packages/*'], dependencies: { '@clerk/nextjs': '^7.0.0' } });
+    writePackage(path.join(root, 'packages', 'ui'), { name: 'ui', dependencies: { react: '^19.0.0' } });
+
+    expect(detectClerkAgentRuleSdks(root)).toEqual(['nextjs']);
+  });
+
+  it('combines SDKs from the workspace root and its packages', () => {
+    writePackage(root, { name: 'app', workspaces: ['packages/*'], dependencies: { '@clerk/nextjs': '^7.0.0' } });
+    writePackage(path.join(root, 'packages', 'api'), { name: 'api', dependencies: { '@clerk/express': '^2.0.0' } });
+
+    expect(detectClerkAgentRuleSdks(path.join(root, 'packages', 'api'))).toEqual(['express', 'nextjs']);
+  });
+});

packages/upgrade/src/__tests__/integration/cli.test.js

@@ -208,6 +208,27 @@ describe('CLI Integration', () => {
     });
   });
 
+  describe('--agents-md flag without a Clerk SDK', () => {
+    let fixture;
+
+    beforeEach(() => {
+      fixture = createTempFixture('no-clerk');
+    });
+
+    afterEach(() => {
+      fixture?.cleanup();
+    });
+
+    it('exits with a failure status and writes nothing', async () => {
+      const fs = await import('node:fs');
+      const result = await runCli(['--dir', fixture.path, '--agents-md'], { timeout: 15000 });
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout + result.stderr).toContain('No Clerk SDK packages found for AGENTS.md');
+      expect(fs.existsSync(path.join(fixture.path, 'AGENTS.md'))).toBe(false);
+    });
+  });
+
   describe('Version Display', () => {
     it('shows current version in output', async () => {
       const dir = getFixturePath('nextjs-v6');

packages/upgrade/src/cli.js

@@ -246,13 +246,6 @@ async function main() {
 
   console.log('');
 
-  if (isInteractive) {
-    const sdks = detectClerkAgentRuleSdks(options.dir);
-    if (sdks.length > 0 && (await promptConfirm('Write Clerk AGENTS.md sections?', true))) {
-      writeAgentsMd(options, sdks);
-    }
-  }
-
   // Step 6: Handle upgrade status
   if (options.skipUpgrade) {
     renderText('Skipping package upgrade (--skip-upgrade flag)', 'yellow');
@@ -268,6 +261,13 @@ async function main() {
     await performPackageReplacements(packageManager, config, options);
   }
 
+  if (isInteractive) {
+    const sdks = detectClerkAgentRuleSdks(options.dir);
+    if (sdks.length > 0 && (await promptConfirm('Write Clerk AGENTS.md sections?', true))) {
+      writeAgentsMd(options, sdks);
+    }
+  }
+
   // Step 7: Run codemods
   if (config.codemods?.length > 0) {
     renderText(`Running ${config.codemods.length} codemod(s)...`, 'blue');
@@ -292,6 +292,7 @@ function writeAgentsMd(options, detectedSdks) {
 
   if (sdks.length === 0) {
     renderWarning('No Clerk SDK packages found for AGENTS.md');
+    process.exitCode = 1;
     return;
   }
 

packages/upgrade/src/util/agent-rules.js

@@ -7,7 +7,7 @@ import { findWorkspaceRoot, getInstalledClerkPackages, getWorkspacePackageDirs }
 
 export function detectClerkAgentRuleSdks(dir) {
   const workspaceRoot = findWorkspaceRoot(dir);
-  const packageDirs = workspaceRoot ? getWorkspacePackageDirs(workspaceRoot) : [dir];
+  const packageDirs = workspaceRoot ? [workspaceRoot, ...getWorkspacePackageDirs(workspaceRoot)] : [dir];
   const sdks = new Set();
 
   for (const packageDir of packageDirs) {