[JIRA-61] Add global disable backup configuration and update related functionality

Author: fraserk-xero

README.md

@@ -160,7 +160,7 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 | `--no-gitignore`               | Disable automatic .gitignore updates                                                                                                                       |
 | `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                        |
 | `--verbose` / `-v`             | Display detailed output during execution                                                                                                                   |
-| `--disable-backup`             | Disable creation of `.bak` backup files when applying rules (default: false)                                                                              |
+| `--disable-backup`             | Disable creation of `.bak` backup files when applying rules (default: false, configurable via `disable_backup` in `ruler.toml`)                        |
 
 ### Common Examples
 
@@ -282,6 +282,10 @@ Defaults to `.ruler/ruler.toml` in the project root. Override with `--config` CL
 # Uses case-insensitive substring matching
 default_agents = ["copilot", "claude", "aider"]
 
+# Global backup setting - disable creation of .bak backup files 
+# (default: false, meaning backups are enabled by default)
+disable_backup = false
+
 # --- Global MCP Server Configuration ---
 [mcp]
 # Enable/disable MCP propagation globally (default: true)

src/agents/GooseAgent.ts

@@ -27,7 +27,7 @@ export class GooseAgent implements IAgent {
       this.getDefaultOutputPath(projectRoot);
 
     // Write rules to .goosehints
-    await backupFile(hintsPath);
+    await backupFile(hintsPath, agentConfig?.disableBackup);
     await writeGeneratedFile(hintsPath, concatenatedRules);
   }
 

src/agents/OpenCodeAgent.ts

@@ -20,7 +20,7 @@ export class OpenCodeAgent implements IAgent {
     const outputPath =
       agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
     const absolutePath = path.resolve(projectRoot, outputPath);
-    await backupFile(absolutePath);
+    await backupFile(absolutePath, agentConfig?.disableBackup);
     await writeGeneratedFile(absolutePath, concatenatedRules);
   }
 

src/cli/commands.ts

@@ -85,7 +85,13 @@ export function run(): void {
         const verbose = argv.verbose as boolean;
         const dryRun = argv['dry-run'] as boolean;
         const localOnly = argv['local-only'] as boolean;
-        const disableBackup = argv['disable-backup'] as boolean;
+        // Determine backup disable preference: CLI > TOML > Default (false)
+        let backupDisablePreference: boolean | undefined;
+        if (argv['disable-backup'] !== undefined) {
+          backupDisablePreference = argv['disable-backup'] as boolean;
+        } else {
+          backupDisablePreference = undefined; // Let TOML/default decide
+        }
 
         // Determine gitignore preference: CLI > TOML > Default (enabled)
         // yargs handles --no-gitignore by setting gitignore to false
@@ -106,7 +112,7 @@ export function run(): void {
             verbose,
             dryRun,
             localOnly,
-            disableBackup,
+            backupDisablePreference,
           );
           console.log('Ruler apply completed successfully.');
         } catch (err: unknown) {

src/core/ConfigLoader.ts

@@ -41,6 +41,7 @@ const rulerConfigSchema = z.object({
       enabled: z.boolean().optional(),
     })
     .optional(),
+  disable_backup: z.boolean().optional(),
 });
 
 /**
@@ -69,6 +70,8 @@ export interface LoadedConfig {
   mcp?: GlobalMcpConfig;
   /** Gitignore configuration section. */
   gitignore?: GitignoreConfig;
+  /** Global disable backup setting. */
+  disableBackup?: boolean;
 }
 
 /**
@@ -207,11 +210,16 @@ export async function loadConfig(
     gitignoreConfig.enabled = rawGitignoreSection.enabled;
   }
 
+  // Parse global disable_backup setting
+  const disableBackup =
+    typeof raw.disable_backup === 'boolean' ? raw.disable_backup : undefined;
+
   return {
     defaultAgents,
     agentConfigs,
     cliAgents,
     mcp: globalMcpConfig,
     gitignore: gitignoreConfig,
+    disableBackup,
   };
 }

src/core/FileSystemUtils.ts

@@ -97,7 +97,10 @@ export async function writeGeneratedFile(
  * @param filePath The file to backup
  * @param disableBackup If true, skip creating the backup
  */
-export async function backupFile(filePath: string, disableBackup: boolean = false): Promise<void> {
+export async function backupFile(
+  filePath: string,
+  disableBackup: boolean = false,
+): Promise<void> {
   if (disableBackup) {
     return; // Skip backup if disabled
   }

src/lib.ts

@@ -116,7 +116,7 @@ export async function applyAllAgentConfigs(
   verbose = false,
   dryRun = false,
   localOnly = false,
-  disableBackup = false,
+  cliDisableBackup?: boolean,
 ): Promise<void> {
   // Load configuration (default_agents, per-agent overrides, CLI filters)
   logVerbose(
@@ -276,6 +276,17 @@ export async function applyAllAgentConfigs(
     );
   }
 
+  // Handle backup disable setting
+  // Configuration precedence: CLI > TOML > Default (false)
+  let disableBackup: boolean;
+  if (cliDisableBackup !== undefined) {
+    disableBackup = cliDisableBackup;
+  } else if (config.disableBackup !== undefined) {
+    disableBackup = config.disableBackup;
+  } else {
+    disableBackup = false; // Default disabled (backups enabled)
+  }
+
   // Collect all generated file paths for .gitignore
   const generatedPaths: string[] = [];
   let agentsMdWritten = false;

tests/apply-disable-backup.toml.test.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+
+describe('apply-disable-backup.toml', () => {
+  let tmpDir: string;
+  let rulerDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ruler-backup-'));
+    rulerDir = path.join(tmpDir, '.ruler');
+    await fs.mkdir(rulerDir, { recursive: true });
+    
+    // Create a simple instruction file
+    await fs.writeFile(
+      path.join(rulerDir, 'instructions.md'),
+      '# Test Instructions\n\nThis is a test.',
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('does not create backup files when disable_backup=true in TOML', async () => {
+    const toml = `disable_backup = true
+default_agents = ["Claude"]
+`;
+    await fs.writeFile(path.join(rulerDir, 'ruler.toml'), toml);
+    
+    execSync('npm run build', { stdio: 'inherit' });
+    execSync(`node dist/cli/index.js apply --project-root ${tmpDir}`, {
+      stdio: 'inherit',
+    });
+    
+    // Check that no backup files were created
+    const claudeFile = path.join(tmpDir, 'CLAUDE.md');
+    const backupFile = path.join(tmpDir, 'CLAUDE.md.bak');
+    
+    expect(await fs.access(claudeFile).then(() => true).catch(() => false)).toBe(true);
+    expect(await fs.access(backupFile).then(() => true).catch(() => false)).toBe(false);
+  });
+
+  it('creates backup files when disable_backup=false in TOML', async () => {
+    const toml = `disable_backup = false
+default_agents = ["Claude"]
+`;
+    await fs.writeFile(path.join(rulerDir, 'ruler.toml'), toml);
+    
+    // Create a pre-existing file to back up
+    const claudeFile = path.join(tmpDir, 'CLAUDE.md');
+    await fs.writeFile(claudeFile, '# Existing content\n');
+    
+    execSync('npm run build', { stdio: 'inherit' });
+    execSync(`node dist/cli/index.js apply --project-root ${tmpDir}`, {
+      stdio: 'inherit',
+    });
+    
+    // Check that backup file was created
+    const backupFile = path.join(tmpDir, 'CLAUDE.md.bak');
+    
+    expect(await fs.access(claudeFile).then(() => true).catch(() => false)).toBe(true);
+    expect(await fs.access(backupFile).then(() => true).catch(() => false)).toBe(true);
+    
+    const backupContent = await fs.readFile(backupFile, 'utf8');
+    expect(backupContent).toBe('# Existing content\n');
+  });
+
+  it('CLI --disable-backup overrides TOML disable_backup=false', async () => {
+    const toml = `disable_backup = false
+default_agents = ["Claude"]
+`;
+    await fs.writeFile(path.join(rulerDir, 'ruler.toml'), toml);
+    
+    // Create a pre-existing file to back up
+    const claudeFile = path.join(tmpDir, 'CLAUDE.md');
+    await fs.writeFile(claudeFile, '# Existing content\n');
+    
+    execSync('npm run build', { stdio: 'inherit' });
+    execSync(`node dist/cli/index.js apply --disable-backup --project-root ${tmpDir}`, {
+      stdio: 'inherit',
+    });
+    
+    // Check that no backup file was created despite TOML setting
+    const backupFile = path.join(tmpDir, 'CLAUDE.md.bak');
+    
+    expect(await fs.access(claudeFile).then(() => true).catch(() => false)).toBe(true);
+    expect(await fs.access(backupFile).then(() => true).catch(() => false)).toBe(false);
+  });
+});

tests/unit/core/ConfigLoader.test.ts

@@ -154,4 +154,33 @@ it('loads config from custom path via configPath option', async () => {
       expect(config.gitignore?.enabled).toBeUndefined();
     });
   });
+
+  describe('disable_backup configuration', () => {
+    it('parses disable_backup = true', async () => {
+      const content = `disable_backup = true`;
+      await fs.writeFile(path.join(rulerDir, 'ruler.toml'), content);
+      const config = await loadConfig({ projectRoot: tmpDir });
+      expect(config.disableBackup).toBe(true);
+    });
+
+    it('parses disable_backup = false', async () => {
+      const content = `disable_backup = false`;
+      await fs.writeFile(path.join(rulerDir, 'ruler.toml'), content);
+      const config = await loadConfig({ projectRoot: tmpDir });
+      expect(config.disableBackup).toBe(false);
+    });
+
+    it('handles missing disable_backup key', async () => {
+      const content = `default_agents = ["A"]`;
+      await fs.writeFile(path.join(rulerDir, 'ruler.toml'), content);
+      const config = await loadConfig({ projectRoot: tmpDir });
+      expect(config.disableBackup).toBeUndefined();
+    });
+
+    it('handles empty config file for disable_backup', async () => {
+      await fs.writeFile(path.join(rulerDir, 'ruler.toml'), '');
+      const config = await loadConfig({ projectRoot: tmpDir });
+      expect(config.disableBackup).toBeUndefined();
+    });
+  });
 });