diff --git a/README.md b/README.md index 607e1f2..4652238 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ That's it! The rule will now be automatically injected into all AI agent prompts Rules are automatically discovered from these directories (including all subdirectories): -1. **Global rules**: `$XDG_CONFIG_HOME/opencode/rules/` (typically `~/.config/opencode/rules/`) +1. **Global rules**: `$OPENCODE_CONFIG_DIR/rules/` if set, otherwise `$XDG_CONFIG_HOME/opencode/rules/` (typically `~/.config/opencode/rules/`) 2. **Project rules**: `.opencode/rules/` (in your project root) Both directories are scanned recursively, allowing you to organize rules into subdirectories. diff --git a/docs/rules.md b/docs/rules.md index 3ecdd6f..952bbdc 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -10,7 +10,7 @@ This document explains how to use OpenCode Rules to inject custom instructions i Rules are defined in Markdown files (`.md` or `.mdc`). These files can be located in two places: -- **Global Rules:** `~/.config/opencode/rules/` +- **Global Rules:** `$OPENCODE_CONFIG_DIR/rules/` if set, otherwise `$XDG_CONFIG_HOME/opencode/rules/` (typically `~/.config/opencode/rules/`) - **Project Rules:** `.opencode/rules/` in the root of your project. Both directories are scanned **recursively**, so you can organize your rules into subdirectories. Rule discovery happens once when the plugin initializes. diff --git a/src/index.integration.test.ts b/src/index.integration.test.ts index 8ffb146..27acef4 100644 --- a/src/index.integration.test.ts +++ b/src/index.integration.test.ts @@ -19,10 +19,13 @@ import { __testOnly } from './index.js'; describe('readAndFormatRules', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; clearRuleCache(); }); @@ -33,6 +36,11 @@ describe('readAndFormatRules', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('should read and format rule files into a formatted string', async () => { @@ -411,10 +419,13 @@ All dimensions must match.` describe('Cross-Dimension Regression Coverage', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; clearRuleCache(); }); @@ -425,6 +436,11 @@ describe('Cross-Dimension Regression Coverage', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); describe('omitted match behaves as any', () => { @@ -825,10 +841,13 @@ Excluded rule.` describe('Conditional rules integration', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; clearRuleCache(); }); @@ -841,6 +860,11 @@ describe('Conditional rules integration', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('should include conditional rule when message context matches glob', async () => { @@ -1032,10 +1056,13 @@ Special rule content.` describe('Session compacting behavior', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; clearRuleCache(); }); @@ -1048,6 +1075,11 @@ describe('Session compacting behavior', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('adds minimal working-set context during compaction', async () => { diff --git a/src/index.rules.test.ts b/src/index.rules.test.ts index 2c85ace..324ef1f 100644 --- a/src/index.rules.test.ts +++ b/src/index.rules.test.ts @@ -988,7 +988,7 @@ describe('discoverRuleFiles', () => { beforeEach(() => { setupTestDirs(); - envSnapshot = saveEnv('XDG_CONFIG_HOME', 'HOME'); + envSnapshot = saveEnv('XDG_CONFIG_HOME', 'HOME', 'OPENCODE_CONFIG_DIR'); }); afterEach(() => { @@ -1068,6 +1068,49 @@ describe('discoverRuleFiles', () => { const files = await discoverRuleFiles(); expect(files.every(f => !f.filePath.includes('.hidden.md'))).toBe(true); }); + + it('should use OPENCODE_CONFIG_DIR/rules as global dir when set', async () => { + const { testDir } = getTestDirs(); + const customDir = path.join(testDir, 'custom-config'); + const customRulesDir = path.join(customDir, 'rules'); + mkdirSync(customRulesDir, { recursive: true }); + writeFileSync(path.join(customRulesDir, 'custom.md'), '# Custom Rule'); + + process.env.OPENCODE_CONFIG_DIR = customDir; + + const files = await discoverRuleFiles(); + expect( + files.some(f => f.filePath === path.join(customRulesDir, 'custom.md')) + ).toBe(true); + }); + + it('should prefer OPENCODE_CONFIG_DIR over XDG_CONFIG_HOME', async () => { + const { testDir, globalRulesDir } = getTestDirs(); + writeFileSync(path.join(globalRulesDir, 'xdg-rule.md'), '# XDG Rule'); + + const customDir = path.join(testDir, 'custom-config'); + const customRulesDir = path.join(customDir, 'rules'); + mkdirSync(customRulesDir, { recursive: true }); + writeFileSync(path.join(customRulesDir, 'custom.md'), '# Custom Rule'); + + process.env.XDG_CONFIG_HOME = path.join(testDir, '.config'); + process.env.OPENCODE_CONFIG_DIR = customDir; + + const files = await discoverRuleFiles(); + expect(files.some(f => f.filePath.includes('custom.md'))).toBe(true); + expect(files.some(f => f.filePath.includes('xdg-rule.md'))).toBe(false); + }); + + it('should handle missing OPENCODE_CONFIG_DIR/rules gracefully', async () => { + const { testDir } = getTestDirs(); + const customDir = path.join(testDir, 'no-rules-here'); + mkdirSync(customDir, { recursive: true }); + + process.env.OPENCODE_CONFIG_DIR = customDir; + + const files = await discoverRuleFiles(); + expect(files).toEqual([]); + }); }); describe('project rules discovery', () => { diff --git a/src/index.runtime.test.ts b/src/index.runtime.test.ts index 5726933..2034e04 100644 --- a/src/index.runtime.test.ts +++ b/src/index.runtime.test.ts @@ -166,10 +166,13 @@ describe('module boundary tests', () => { describe('OpenCodeRulesPlugin', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; }); afterEach(() => { @@ -181,6 +184,11 @@ describe('OpenCodeRulesPlugin', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('should export a plugin module with id and server', async () => { @@ -381,10 +389,13 @@ describe('OpenCodeRulesPlugin', () => { describe('SessionState', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; }); afterEach(async () => { @@ -396,6 +407,11 @@ describe('SessionState', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('prunes session state when over limit', async () => { @@ -731,11 +747,14 @@ describe('SessionState', () => { describe('Active rules state persistence', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; let stateDir: string; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; const { testDir } = getTestDirs(); stateDir = path.join(testDir, 'state'); mkdirSync(stateDir, { recursive: true }); @@ -752,6 +771,11 @@ describe('Active rules state persistence', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('writes matched rule paths to state file when rules match', async () => { @@ -892,11 +916,14 @@ describe('session-store runtime exports', () => { describe('CI environment detection', () => { let savedCiEnv: CiEnvSnapshot; let savedXDG: string | undefined; + let savedConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedCiEnv = saveCiEnvVars(); savedXDG = process.env.XDG_CONFIG_HOME; + savedConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; }); afterEach(async () => { @@ -909,6 +936,11 @@ describe('CI environment detection', () => { } else { process.env.XDG_CONFIG_HOME = savedXDG; } + if (savedConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedConfigDir; + } }); it('should include ci-conditional rule when CI env var is set', async () => { diff --git a/src/index.test.ts b/src/index.test.ts index fdf804f..ee1bc15 100644 --- a/src/index.test.ts +++ b/src/index.test.ts @@ -31,11 +31,14 @@ import { // Retained plugin-level tests with complex runtime filter context describe('Runtime filter context integration (plugin-level)', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; let savedCiEnv: CiEnvSnapshot; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; savedCiEnv = saveCiEnvVars(); clearRuleCache(); }); @@ -50,6 +53,11 @@ describe('Runtime filter context integration (plugin-level)', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('should include model-conditional rule when session has matching modelID', async () => { @@ -588,10 +596,13 @@ Feature branch guidelines.` // Retained API contract tests describe('readAndFormatRules API contract', () => { let savedEnvXDG: string | undefined; + let savedEnvConfigDir: string | undefined; beforeEach(() => { setupTestDirs(); savedEnvXDG = process.env.XDG_CONFIG_HOME; + savedEnvConfigDir = process.env.OPENCODE_CONFIG_DIR; + delete process.env.OPENCODE_CONFIG_DIR; clearRuleCache(); }); @@ -602,6 +613,11 @@ describe('readAndFormatRules API contract', () => { } else { process.env.XDG_CONFIG_HOME = savedEnvXDG; } + if (savedEnvConfigDir === undefined) { + delete process.env.OPENCODE_CONFIG_DIR; + } else { + process.env.OPENCODE_CONFIG_DIR = savedEnvConfigDir; + } }); it('should only accept RuleFilterContext object as second argument', async () => { diff --git a/src/rule-discovery.ts b/src/rule-discovery.ts index 3148ce5..36154fa 100644 --- a/src/rule-discovery.ts +++ b/src/rule-discovery.ts @@ -91,6 +91,11 @@ export async function getCachedRule( * Get the global rules directory path */ function getGlobalRulesDir(): string | null { + const opencodeConfigDir = process.env.OPENCODE_CONFIG_DIR; + if (opencodeConfigDir) { + return path.join(opencodeConfigDir, 'rules'); + } + const xdgConfigHome = process.env.XDG_CONFIG_HOME; if (xdgConfigHome) { return path.join(xdgConfigHome, 'opencode', 'rules'); @@ -160,6 +165,7 @@ export interface DiscoveredRule { /** * Discover markdown rule files from standard directories * Searches recursively in: + * - $OPENCODE_CONFIG_DIR/rules/ (highest priority) * - $XDG_CONFIG_HOME/opencode/rules/ (or ~/.config/opencode/rules as fallback) * - .opencode/rules/ (in project directory if provided) * Finds all .md and .mdc files including nested subdirectories. diff --git a/tui/data/rules.test.ts b/tui/data/rules.test.ts index f2dc669..c274ff4 100644 --- a/tui/data/rules.test.ts +++ b/tui/data/rules.test.ts @@ -215,10 +215,13 @@ describe('disambiguateNames', () => { describe('loadSidebarRules', () => { let testDir: string; let savedXDG: string | undefined; + let savedConfigDir: string | undefined; beforeEach(() => { testDir = mkdtempSync(path.join(os.tmpdir(), 'tui-rules-test-')); savedXDG = process.env['XDG_CONFIG_HOME']; + savedConfigDir = process.env['OPENCODE_CONFIG_DIR']; + delete process.env['OPENCODE_CONFIG_DIR']; clearRuleCache(); }); @@ -229,6 +232,11 @@ describe('loadSidebarRules', () => { } else { process.env['XDG_CONFIG_HOME'] = savedXDG; } + if (savedConfigDir === undefined) { + delete process.env['OPENCODE_CONFIG_DIR']; + } else { + process.env['OPENCODE_CONFIG_DIR'] = savedConfigDir; + } }); it('discovers global rules when projectDir is null', async () => { @@ -341,12 +349,15 @@ describe('loadSidebarRules isActive behavior', () => { let testDir: string; let stateDir: string; let savedXDG: string | undefined; + let savedConfigDir: string | undefined; beforeEach(() => { testDir = mkdtempSync(path.join(os.tmpdir(), 'tui-rules-active-test-')); stateDir = path.join(testDir, 'state'); mkdirSync(stateDir, { recursive: true }); savedXDG = process.env['XDG_CONFIG_HOME']; + savedConfigDir = process.env['OPENCODE_CONFIG_DIR']; + delete process.env['OPENCODE_CONFIG_DIR']; clearRuleCache(); _setStateDirForTesting(stateDir); }); @@ -359,6 +370,11 @@ describe('loadSidebarRules isActive behavior', () => { } else { process.env['XDG_CONFIG_HOME'] = savedXDG; } + if (savedConfigDir === undefined) { + delete process.env['OPENCODE_CONFIG_DIR']; + } else { + process.env['OPENCODE_CONFIG_DIR'] = savedConfigDir; + } }); it('sets hasEvaluationState to false when no sessionId provided', async () => {