Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
32 changes: 32 additions & 0 deletions src/index.integration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
});

Expand All @@ -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 () => {
Expand Down Expand Up @@ -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();
});

Expand All @@ -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', () => {
Expand Down Expand Up @@ -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();
});

Expand All @@ -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 () => {
Expand Down Expand Up @@ -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();
});

Expand All @@ -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 () => {
Expand Down
45 changes: 44 additions & 1 deletion src/index.rules.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -988,7 +988,7 @@ describe('discoverRuleFiles', () => {

beforeEach(() => {
setupTestDirs();
envSnapshot = saveEnv('XDG_CONFIG_HOME', 'HOME');
envSnapshot = saveEnv('XDG_CONFIG_HOME', 'HOME', 'OPENCODE_CONFIG_DIR');
});

afterEach(() => {
Expand Down Expand Up @@ -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', () => {
Expand Down
32 changes: 32 additions & 0 deletions src/index.runtime.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(() => {
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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 () => {
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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 });
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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 () => {
Expand All @@ -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 () => {
Expand Down
16 changes: 16 additions & 0 deletions src/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
});
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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();
});

Expand All @@ -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 () => {
Expand Down
6 changes: 6 additions & 0 deletions src/rule-discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down Expand Up @@ -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.
Expand Down
Loading