@intellectronica/ruler 0.2.18 → 0.3.0

package/dist/cli/commands.js

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -39,12 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = run;
 const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
-const lib_1 = require("../lib");
-const revert_1 = require("../revert");
-const path = __importStar(require("path"));
-const os = __importStar(require("os"));
-const fs_1 = require("fs");
-const constants_1 = require("../constants");
+const handlers_1 = require("./handlers");
 /**
  * Sets up and parses CLI commands.
  */
@@ -53,258 +15,102 @@ function run() {
         .scriptName('ruler')
         .usage('$0 <command> [options]')
         .command('apply', 'Apply ruler configurations to supported AI agents', (y) => {
-        y.option('project-root', {
+        return y
+            .option('project-root', {
             type: 'string',
             description: 'Project root directory',
             default: process.cwd(),
-        });
-        y.option('agents', {
+        })
+            .option('agents', {
             type: 'string',
-            description: 'Comma-separated list of agent identifiers: copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush',
-        });
-        y.option('config', {
+            description: 'Comma-separated list of agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush, zed, qwen',
+        })
+            .option('config', {
             type: 'string',
             description: 'Path to TOML configuration file',
-        });
-        y.option('mcp', {
+        })
+            .option('mcp', {
             type: 'boolean',
             description: 'Enable or disable applying MCP server config',
             default: true,
-        });
-        y.alias('mcp', 'with-mcp');
-        y.option('mcp-overwrite', {
+        })
+            .alias('mcp', 'with-mcp')
+            .option('mcp-overwrite', {
             type: 'boolean',
             description: 'Replace (not merge) the native MCP config(s)',
             default: false,
-        });
-        y.option('gitignore', {
+        })
+            .option('gitignore', {
             type: 'boolean',
             description: 'Enable/disable automatic .gitignore updates (default: enabled)',
-        });
-        y.option('verbose', {
+        })
+            .option('verbose', {
             type: 'boolean',
             description: 'Enable verbose logging',
             default: false,
-        });
-        y.alias('verbose', 'v');
-        y.option('dry-run', {
+        })
+            .alias('verbose', 'v')
+            .option('dry-run', {
             type: 'boolean',
             description: 'Preview changes without writing files',
             default: false,
-        });
-        y.option('local-only', {
+        })
+            .option('local-only', {
             type: 'boolean',
             description: 'Only search for local .ruler directories, ignore global config',
             default: false,
         });
-    }, async (argv) => {
-        const projectRoot = argv['project-root'];
-        const agents = argv.agents
-            ? argv.agents.split(',').map((a) => a.trim())
-            : undefined;
-        const configPath = argv.config;
-        const mcpEnabled = argv.mcp;
-        const mcpStrategy = argv['mcp-overwrite']
-            ? 'overwrite'
-            : undefined;
-        const verbose = argv.verbose;
-        const dryRun = argv['dry-run'];
-        const localOnly = argv['local-only'];
-        // Determine gitignore preference: CLI > TOML > Default (enabled)
-        // yargs handles --no-gitignore by setting gitignore to false
-        let gitignorePreference;
-        if (argv.gitignore !== undefined) {
-            gitignorePreference = argv.gitignore;
-        }
-        else {
-            gitignorePreference = undefined; // Let TOML/default decide
-        }
-        try {
-            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly);
-            console.log('Ruler apply completed successfully.');
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`${constants_1.ERROR_PREFIX} ${message}`);
-            process.exit(1);
-        }
-    })
+    }, handlers_1.applyHandler)
         .command('init', 'Scaffold a .ruler directory with default files', (y) => {
-        y.option('project-root', {
+        return y
+            .option('project-root', {
             type: 'string',
             description: 'Project root directory',
             default: process.cwd(),
-        }).option('global', {
+        })
+            .option('global', {
             type: 'boolean',
             description: 'Initialize in global config directory (XDG_CONFIG_HOME/ruler)',
             default: false,
         });
-    }, async (argv) => {
-        const projectRoot = argv['project-root'];
-        const isGlobal = argv['global'];
-        const rulerDir = isGlobal
-            ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
-            : path.join(projectRoot, '.ruler');
-        await fs_1.promises.mkdir(rulerDir, { recursive: true });
-        const instructionsPath = path.join(rulerDir, 'instructions.md');
-        const tomlPath = path.join(rulerDir, 'ruler.toml');
-        const exists = async (p) => {
-            try {
-                await fs_1.promises.access(p);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        };
-        const DEFAULT_INSTRUCTIONS = `# Ruler Instructions
-
-These are your centralised AI agent instructions.
-Add your coding guidelines, style guides, and other project-specific context here.
-
-Ruler will concatenate all .md files in this directory (and its subdirectories)
-and apply them to your configured AI coding agents.
-`;
-        const DEFAULT_TOML = `# Ruler Configuration File
-# See https://ai.intellectronica.net/ruler for documentation.
-
-# To specify which agents are active by default when --agents is not used,
-# uncomment and populate the following line. If omitted, all agents are active.
-# default_agents = ["copilot", "claude"]
-
-# --- Agent Specific Configurations ---
-# You can enable/disable agents and override their default output paths here.
-# Use lowercase agent identifiers: copilot, claude, codex, cursor, windsurf, cline, aider, kilocode
-
-# [agents.copilot]
-# enabled = true
-# output_path = ".github/copilot-instructions.md"
-
-# [agents.claude]
-# enabled = true
-# output_path = "CLAUDE.md"
-
-# [agents.codex]
-# enabled = true
-# output_path = "AGENTS.md"
-
-# [agents.cursor]
-# enabled = true
-# output_path = ".cursor/rules/ruler_cursor_instructions.mdc"
-
-# [agents.windsurf]
-# enabled = true
-# output_path = ".windsurf/rules/ruler_windsurf_instructions.md"
-
-# [agents.cline]
-# enabled = true
-# output_path = ".clinerules"
-
-# [agents.aider]
-# enabled = true
-# output_path_instructions = "ruler_aider_instructions.md"
-# output_path_config = ".aider.conf.yml"
-
-# [agents.firebase]
-# enabled = true
-# output_path = ".idx/airules.md"
-
-# [agents.gemini-cli]
-# enabled = true
-
-# [agents.kilocode]
-# enabled = true
-# output_path = ".kilocode/rules/ruler_kilocode_instructions.md"
-`;
-        if (!(await exists(instructionsPath))) {
-            await fs_1.promises.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
-            console.log(`[ruler] Created ${instructionsPath}`);
-        }
-        else {
-            console.log(`[ruler] instructions.md already exists, skipping`);
-        }
-        if (!(await exists(tomlPath))) {
-            await fs_1.promises.writeFile(tomlPath, DEFAULT_TOML);
-            console.log(`[ruler] Created ${tomlPath}`);
-        }
-        else {
-            console.log(`[ruler] ruler.toml already exists, skipping`);
-        }
-        const mcpPath = path.join(rulerDir, 'mcp.json');
-        const DEFAULT_MCP_JSON = `{
-  "mcpServers": {
-    "example": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/path/to/mcp-server.js"],
-      "env": {
-        "NODE_ENV": "production"
-      }
-    }
-  }
-}\n`;
-        if (!(await exists(mcpPath))) {
-            await fs_1.promises.writeFile(mcpPath, DEFAULT_MCP_JSON);
-            console.log(`[ruler] Created ${mcpPath}`);
-        }
-        else {
-            console.log(`[ruler] mcp.json already exists, skipping`);
-        }
-    })
-        .command('revert', 'Revert ruler configurations by restoring backups and removing generated files', (y) => {
-        y.option('project-root', {
+    }, handlers_1.initHandler)
+        .command('revert', 'Revert ruler configurations from supported AI agents', (y) => {
+        return y
+            .option('project-root', {
             type: 'string',
             description: 'Project root directory',
             default: process.cwd(),
-        });
-        y.option('agents', {
+        })
+            .option('agents', {
             type: 'string',
-            description: 'Comma-separated list of agent identifiers: copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush',
-        });
-        y.option('config', {
+            description: 'Comma-separated list of agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush, zed, qwen',
+        })
+            .option('config', {
             type: 'string',
             description: 'Path to TOML configuration file',
-        });
-        y.option('keep-backups', {
+        })
+            .option('keep-backups', {
             type: 'boolean',
-            description: 'Keep backup files (.bak) after restoration',
+            description: 'Keep backup files after revert',
             default: false,
-        });
-        y.option('verbose', {
+        })
+            .option('verbose', {
             type: 'boolean',
             description: 'Enable verbose logging',
             default: false,
-        });
-        y.alias('verbose', 'v');
-        y.option('dry-run', {
+        })
+            .alias('verbose', 'v')
+            .option('dry-run', {
             type: 'boolean',
-            description: 'Preview changes without actually reverting files',
+            description: 'Preview changes without writing files',
             default: false,
-        });
-        y.option('local-only', {
+        })
+            .option('local-only', {
             type: 'boolean',
             description: 'Only search for local .ruler directories, ignore global config',
             default: false,
         });
-    }, async (argv) => {
-        const projectRoot = argv['project-root'];
-        const agents = argv.agents
-            ? argv.agents.split(',').map((a) => a.trim())
-            : undefined;
-        const configPath = argv.config;
-        const keepBackups = argv['keep-backups'];
-        const verbose = argv.verbose;
-        const dryRun = argv['dry-run'];
-        const localOnly = argv['local-only'];
-        try {
-            await (0, revert_1.revertAllAgentConfigs)(projectRoot, agents, configPath, keepBackups, verbose, dryRun, localOnly);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`${constants_1.ERROR_PREFIX} ${message}`);
-            process.exit(1);
-        }
-    })
+    }, handlers_1.revertHandler)
         .demandCommand(1, 'You need to specify a command')
         .help()
         .strict()

package/dist/cli/handlers.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyHandler = applyHandler;
+exports.initHandler = initHandler;
+exports.revertHandler = revertHandler;
+const lib_1 = require("../lib");
+const revert_1 = require("../revert");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs/promises"));
+const constants_1 = require("../constants");
+/**
+ * Handler for the 'apply' command.
+ */
+async function applyHandler(argv) {
+    const projectRoot = argv['project-root'];
+    const agents = argv.agents
+        ? argv.agents.split(',').map((a) => a.trim())
+        : undefined;
+    const configPath = argv.config;
+    const mcpEnabled = argv.mcp;
+    const mcpStrategy = argv['mcp-overwrite']
+        ? 'overwrite'
+        : undefined;
+    const verbose = argv.verbose;
+    const dryRun = argv['dry-run'];
+    const localOnly = argv['local-only'];
+    // Determine gitignore preference: CLI > TOML > Default (enabled)
+    // yargs handles --no-gitignore by setting gitignore to false
+    let gitignorePreference;
+    if (argv.gitignore !== undefined) {
+        gitignorePreference = argv.gitignore;
+    }
+    else {
+        gitignorePreference = undefined; // Let TOML/default decide
+    }
+    try {
+        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly);
+        console.log('Ruler apply completed successfully.');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        process.exit(1);
+    }
+}
+/**
+ * Handler for the 'init' command.
+ */
+async function initHandler(argv) {
+    const projectRoot = argv['project-root'];
+    const isGlobal = argv['global'];
+    const rulerDir = isGlobal
+        ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
+        : path.join(projectRoot, '.ruler');
+    await fs.mkdir(rulerDir, { recursive: true });
+    const instructionsPath = path.join(rulerDir, constants_1.DEFAULT_RULES_FILENAME); // .ruler/AGENTS.md
+    const tomlPath = path.join(rulerDir, 'ruler.toml');
+    const exists = async (p) => {
+        try {
+            await fs.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const DEFAULT_INSTRUCTIONS = `# AGENTS.md\n\nCentralised AI agent instructions. Add coding guidelines, style guides, and project context here.\n\nRuler concatenates all .md files in this directory (and subdirectories), starting with AGENTS.md (if present), then remaining files in sorted order.\n`;
+    const DEFAULT_TOML = `# Ruler Configuration File
+# See https://ai.intellectronica.net/ruler for documentation.
+
+# To specify which agents are active by default when --agents is not used,
+# uncomment and populate the following line. If omitted, all agents are active.
+# default_agents = ["copilot", "claude"]
+
+# --- Agent Specific Configurations ---
+# You can enable/disable agents and override their default output paths here.
+# Use lowercase agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, kilocode
+
+# [agents.copilot]
+# enabled = true
+# output_path = ".github/copilot-instructions.md"
+
+# [agents.aider]
+# enabled = true
+# output_path_instructions = "AGENTS.md"
+# output_path_config = ".aider.conf.yml"
+
+# [agents.gemini-cli]
+# enabled = true
+
+# --- MCP Servers ---
+# Define Model Context Protocol servers here. Two examples:
+# 1. A stdio server (local executable)
+# 2. A remote server (HTTP-based)
+
+# [mcp_servers.example_stdio]
+# command = "node"
+# args = ["scripts/your-mcp-server.js"]
+# env = { API_KEY = "replace_me" }
+
+# [mcp_servers.example_remote]
+# url = "https://api.example.com/mcp"
+# headers = { Authorization = "Bearer REPLACE_ME" }
+`;
+    if (!(await exists(instructionsPath))) {
+        // Create new AGENTS.md regardless of legacy presence.
+        await fs.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
+        console.log(`[ruler] Created ${instructionsPath}`);
+    }
+    else {
+        console.log(`[ruler] ${constants_1.DEFAULT_RULES_FILENAME} already exists, skipping`);
+    }
+    if (!(await exists(tomlPath))) {
+        await fs.writeFile(tomlPath, DEFAULT_TOML);
+        console.log(`[ruler] Created ${tomlPath}`);
+    }
+    else {
+        console.log(`[ruler] ruler.toml already exists, skipping`);
+    }
+}
+/**
+ * Handler for the 'revert' command.
+ */
+async function revertHandler(argv) {
+    const projectRoot = argv['project-root'];
+    const agents = argv.agents
+        ? argv.agents.split(',').map((a) => a.trim())
+        : undefined;
+    const configPath = argv.config;
+    const keepBackups = argv['keep-backups'];
+    const verbose = argv.verbose;
+    const dryRun = argv['dry-run'];
+    const localOnly = argv['local-only'];
+    try {
+        await (0, revert_1.revertAllAgentConfigs)(projectRoot, agents, configPath, keepBackups, verbose, dryRun, localOnly);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        process.exit(1);
+    }
+}

package/dist/constants.js

@@ -1,9 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ERROR_PREFIX = void 0;
+exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
+exports.actionPrefix = actionPrefix;
 exports.createRulerError = createRulerError;
 exports.logVerbose = logVerbose;
-exports.ERROR_PREFIX = '[RulerError]';
+exports.ERROR_PREFIX = '[ruler]';
+// Centralized default rules filename. Now points to 'AGENTS.md'.
+// Legacy '.ruler/instructions.md' is still supported as a fallback with a warning.
+exports.DEFAULT_RULES_FILENAME = 'AGENTS.md';
+function actionPrefix(dry) {
+    return dry ? '[ruler:dry-run]' : '[ruler]';
+}
 function createRulerError(message, context) {
     const fullMessage = context
         ? `${exports.ERROR_PREFIX} ${message} (Context: ${context})`

package/dist/core/ConfigLoader.js

@@ -105,7 +105,7 @@ async function loadConfig(options) {
     }
     catch (err) {
         if (err instanceof Error && err.code !== 'ENOENT') {
-            if (err.message.includes('[RulerError]')) {
+            if (err.message.includes('[ruler]')) {
                 throw err; // Re-throw validation errors
             }
             console.warn(`[ruler] Warning: could not read config file at ${configFile}: ${err.message}`);

package/dist/core/FileSystemUtils.js

@@ -92,7 +92,8 @@ async function findRulerDir(startPath, checkGlobal = true) {
  * Files are sorted alphabetically by path.
  */
 async function readMarkdownFiles(rulerDir) {
-    const results = [];
+    const mdFiles = [];
+    // Gather all markdown files (recursive) first
     async function walk(dir) {
         const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
@@ -102,13 +103,59 @@ async function readMarkdownFiles(rulerDir) {
             }
             else if (entry.isFile() && entry.name.endsWith('.md')) {
                 const content = await fs_1.promises.readFile(fullPath, 'utf8');
-                results.push({ path: fullPath, content });
+                mdFiles.push({ path: fullPath, content });
             }
         }
     }
     await walk(rulerDir);
-    results.sort((a, b) => a.path.localeCompare(b.path));
-    return results;
+    // Prioritisation logic:
+    // 1. Prefer top-level AGENTS.md if present.
+    // 2. If AGENTS.md absent but legacy instructions.md present, use it (no longer emits a warning; legacy accepted silently).
+    // 3. Include any remaining .md files (excluding whichever of the above was used if present) in
+    //    sorted order AFTER the preferred primary file so that new concatenation priority starts with AGENTS.md.
+    const topLevelAgents = path.join(rulerDir, 'AGENTS.md');
+    const topLevelLegacy = path.join(rulerDir, 'instructions.md');
+    // Separate primary candidates from others
+    let primaryFile = null;
+    const others = [];
+    for (const f of mdFiles) {
+        if (f.path === topLevelAgents) {
+            primaryFile = f; // Highest priority
+        }
+    }
+    if (!primaryFile) {
+        for (const f of mdFiles) {
+            if (f.path === topLevelLegacy) {
+                primaryFile = f;
+                break;
+            }
+        }
+    }
+    for (const f of mdFiles) {
+        if (primaryFile && f.path === primaryFile.path)
+            continue;
+        others.push(f);
+    }
+    // Sort the remaining others for stable deterministic concatenation order.
+    others.sort((a, b) => a.path.localeCompare(b.path));
+    let ordered = primaryFile ? [primaryFile, ...others] : others;
+    // NEW: Prepend repository root AGENTS.md (outside .ruler) if it exists and is not identical path.
+    try {
+        const repoRoot = path.dirname(rulerDir); // .ruler parent
+        const rootAgentsPath = path.join(repoRoot, 'AGENTS.md');
+        if (path.resolve(rootAgentsPath) !== path.resolve(topLevelAgents)) {
+            const stat = await fs_1.promises.stat(rootAgentsPath);
+            if (stat.isFile()) {
+                const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
+                // Prepend so it has highest precedence
+                ordered = [{ path: rootAgentsPath, content }, ...ordered];
+            }
+        }
+    }
+    catch {
+        // ignore if root AGENTS.md not present
+    }
+    return ordered;
 }
 /**
  * Writes content to filePath, creating parent directories if necessary.

package/dist/core/RuleProcessor.js

@@ -39,10 +39,22 @@ const path = __importStar(require("path"));
  * Concatenates markdown rule files into a single string,
  * marking each section with its source filename.
  */
-function concatenateRules(files) {
+function concatenateRules(files, baseDir) {
+    const base = baseDir || process.cwd();
     const sections = files.map(({ path: filePath, content }) => {
-        const rel = path.relative(process.cwd(), filePath);
-        return ['---', `Source: ${rel}`, '---', content.trim(), ''].join('\n');
+        const rel = path.relative(base, filePath);
+        // Normalize path separators to forward slashes for consistent output across platforms
+        const normalizedRel = rel.replace(/\\/g, '/');
+        // New format: two leading blank lines, HTML comment with source, one blank line, then content, then trailing newline
+        // We intentionally trim content to avoid cascading blank lines, then ensure a final newline via join logic
+        return [
+            '', // first leading blank line
+            '', // second leading blank line
+            `<!-- Source: ${normalizedRel} -->`,
+            '', // single blank line after the comment
+            content.trim(),
+            '', // ensure file section ends with newline
+        ].join('\n');
     });
     return sections.join('\n');
 }