refactor(hermesagent): collapse repeated path expressions and align checks output root

docs/reference/cli-commands.md

@@ -123,6 +123,12 @@ rulesync generate --dry-run --targets claudecode --features rules
 rulesync generate --check --targets "*" --features "*"
 ```
 
+### Tool home overrides win over the output root in global scope
+
+Two tools read their profile location from an environment variable: Hermes Agent (`HERMES_HOME`) and Kimi Code (`KIMI_CODE_HOME`). When one of them is set, `generate --global` and `convert --global` write that tool's output under it, **overriding both `outputRoots` and an explicit `--output-roots`** for that target. See [Supported Tools](./supported-tools.md) for what each profile root contains. This is deliberate — the variable names where the tool itself looks, so honoring the flag instead would produce files the tool never reads. Every other target still uses the configured output root.
+
+The override must be a usable directory: an empty value is ignored (the default profile location applies), and a value that is the filesystem root or an unnormalized path is rejected with an error naming the variable.
+
 ### Shared config files are never created empty
 
 Some outputs are files Rulesync merges into rather than owns, because the tool (or you) keeps unrelated settings there: `.amp/settings.json(c)`, `.antigravity/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `.codex/config.toml`, `.devin/config.json`, `.factory/settings.json`, `.grok/config.toml`, `.vibe/config.toml`, `.vscode/settings.json`, `.zed/settings.json`, `kilo.json(c)`, `opencode.json(c)`, and `reasonix.toml`. These are deliberately **not** added to `.gitignore` by `rulesync gitignore`, so that settings you hand-author in them stay version-controlled.

skills/rulesync/cli-commands.md

@@ -123,6 +123,12 @@ rulesync generate --dry-run --targets claudecode --features rules
 rulesync generate --check --targets "*" --features "*"
 ```
 
+### Tool home overrides win over the output root in global scope
+
+Two tools read their profile location from an environment variable: Hermes Agent (`HERMES_HOME`) and Kimi Code (`KIMI_CODE_HOME`). When one of them is set, `generate --global` and `convert --global` write that tool's output under it, **overriding both `outputRoots` and an explicit `--output-roots`** for that target. See [Supported Tools](./supported-tools.md) for what each profile root contains. This is deliberate — the variable names where the tool itself looks, so honoring the flag instead would produce files the tool never reads. Every other target still uses the configured output root.
+
+The override must be a usable directory: an empty value is ignored (the default profile location applies), and a value that is the filesystem root or an unnormalized path is rejected with an error naming the variable.
+
 ### Shared config files are never created empty
 
 Some outputs are files Rulesync merges into rather than owns, because the tool (or you) keeps unrelated settings there: `.amp/settings.json(c)`, `.antigravity/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `.codex/config.toml`, `.devin/config.json`, `.factory/settings.json`, `.grok/config.toml`, `.vibe/config.toml`, `.vscode/settings.json`, `.zed/settings.json`, `kilo.json(c)`, `opencode.json(c)`, and `reasonix.toml`. These are deliberately **not** added to `.gitignore` by `rulesync gitignore`, so that settings you hand-author in them stay version-controlled.

src/features/commands/hermesagent-command.ts

@@ -187,28 +187,23 @@ class HermesagentCommandAuxiliaryFile extends ToolFile {
     return { success: true, error: null };
   }
 
-  shouldMergeExistingFileContent(): boolean {
+  /**
+   * Whether this auxiliary file is the one at `relativeFilePath`, comparing
+   * against the scope-resolved location of that canonical `.hermes/...` path.
+   */
+  private matchesPath(relativeFilePath: string): boolean {
     return (
       this.getRelativePathFromCwd() ===
-      toPosixPath(
-        getHermesagentRelativeFilePath({
-          global: this.global,
-          relativeFilePath: HERMESAGENT_CONFIG_FILE_PATH,
-        }),
-      )
+      toPosixPath(getHermesagentRelativeFilePath({ global: this.global, relativeFilePath }))
     );
   }
 
+  shouldMergeExistingFileContent(): boolean {
+    return this.matchesPath(HERMESAGENT_CONFIG_FILE_PATH);
+  }
+
   setFileContent(newFileContent: string): void {
-    if (
-      this.getRelativePathFromCwd() ===
-      toPosixPath(
-        getHermesagentRelativeFilePath({
-          global: this.global,
-          relativeFilePath: HERMESAGENT_CONFIG_FILE_PATH,
-        }),
-      )
-    ) {
+    if (this.matchesPath(HERMESAGENT_CONFIG_FILE_PATH)) {
       super.setFileContent(
         getEnabledPluginConfigContent({ currentContent: newFileContent, global: this.global }),
       );
@@ -218,37 +213,13 @@ class HermesagentCommandAuxiliaryFile extends ToolFile {
   }
 
   getFileContent(): string {
-    if (
-      this.getRelativePathFromCwd() ===
-      toPosixPath(
-        getHermesagentRelativeFilePath({
-          global: this.global,
-          relativeFilePath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_MANIFEST_PATH,
-        }),
-      )
-    ) {
+    if (this.matchesPath(HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_MANIFEST_PATH)) {
       return getPluginManifestContent();
     }
-    if (
-      this.getRelativePathFromCwd() ===
-      toPosixPath(
-        getHermesagentRelativeFilePath({
-          global: this.global,
-          relativeFilePath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_INIT_PATH,
-        }),
-      )
-    ) {
+    if (this.matchesPath(HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_INIT_PATH)) {
       return getPluginInitContent();
     }
-    if (
-      this.getRelativePathFromCwd() ===
-      toPosixPath(
-        getHermesagentRelativeFilePath({
-          global: this.global,
-          relativeFilePath: HERMESAGENT_CONFIG_FILE_PATH,
-        }),
-      )
-    ) {
+    if (this.matchesPath(HERMESAGENT_CONFIG_FILE_PATH)) {
       return getEnabledPluginConfigContent({
         currentContent: super.getFileContent(),
         global: this.global,
@@ -342,33 +313,28 @@ export class HermesagentCommand extends ToolCommand {
     forDeletion?: boolean;
   }): Promise<ToolFile[]> {
     if (toolCommands.length === 0 && !forDeletion) return [];
+    const pluginDirPath = getHermesagentRelativeDirPath({
+      global,
+      relativeDirPath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_DIR_PATH,
+    });
     const pluginFiles: ToolFile[] = [
       new HermesagentCommandAuxiliaryFile({
         outputRoot,
-        relativeDirPath: getHermesagentRelativeDirPath({
-          global,
-          relativeDirPath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_DIR_PATH,
-        }),
+        relativeDirPath: pluginDirPath,
         relativeFilePath: basename(HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_MANIFEST_PATH),
         fileContent: "",
         global,
       }),
       new HermesagentCommandAuxiliaryFile({
         outputRoot,
-        relativeDirPath: getHermesagentRelativeDirPath({
-          global,
-          relativeDirPath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_DIR_PATH,
-        }),
+        relativeDirPath: pluginDirPath,
         relativeFilePath: basename(HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_OWNERSHIP_PATH),
         fileContent: "Generated and owned by RuleSync.\n",
         global,
       }),
       new HermesagentCommandAuxiliaryFile({
         outputRoot,
-        relativeDirPath: getHermesagentRelativeDirPath({
-          global,
-          relativeDirPath: HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_DIR_PATH,
-        }),
+        relativeDirPath: pluginDirPath,
         relativeFilePath: basename(HERMESAGENT_RULESYNC_COMMANDS_PLUGIN_INIT_PATH),
         fileContent: "",
         global,

src/features/hooks/hermesagent-hooks.test.ts

@@ -1,4 +1,6 @@
-import { describe, expect, it, vi } from "vitest";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { createMockLogger } from "../../test-utils/mock-logger.js";
 import { parseSharedConfig } from "../shared/shared-config-gateway.js";
@@ -378,3 +380,35 @@ hooks:
     });
   });
 });
+
+describe("HermesagentHooks global settable paths", () => {
+  // Pinned as literals rather than re-calling getHermesagentGlobalDir(), so the
+  // platform branch itself is asserted and not merely restated.
+  const expectedGlobalDir =
+    process.platform === "win32" ? join("AppData", "Local", "hermes") : ".hermes";
+
+  const originalHermesHome = process.env.HERMES_HOME;
+
+  afterEach(() => {
+    if (originalHermesHome === undefined) delete process.env.HERMES_HOME;
+    else process.env.HERMES_HOME = originalHermesHome;
+  });
+
+  it("anchors global paths on the platform profile directory when HERMES_HOME is unset", () => {
+    delete process.env.HERMES_HOME;
+
+    expect(HermesagentHooks.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: expectedGlobalDir,
+      relativeFilePath: "config.yaml",
+    });
+  });
+
+  it("drops the .hermes prefix when HERMES_HOME names the profile root itself", () => {
+    process.env.HERMES_HOME = "/custom-hermes";
+
+    expect(HermesagentHooks.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: ".",
+      relativeFilePath: "config.yaml",
+    });
+  });
+});

src/features/mcp/hermesagent-mcp.test.ts

@@ -748,3 +748,35 @@ mcp_servers:
     expect(getMcpServers(mcp.getFileContent())["test-server"]?.args).toEqual(["hello"]);
   });
 });
+
+describe("HermesagentMcp global settable paths", () => {
+  // Pinned as literals rather than re-calling getHermesagentGlobalDir(), so the
+  // platform branch itself is asserted and not merely restated.
+  const expectedGlobalDir =
+    process.platform === "win32" ? join("AppData", "Local", "hermes") : ".hermes";
+
+  const originalHermesHome = process.env.HERMES_HOME;
+
+  afterEach(() => {
+    if (originalHermesHome === undefined) delete process.env.HERMES_HOME;
+    else process.env.HERMES_HOME = originalHermesHome;
+  });
+
+  it("anchors global paths on the platform profile directory when HERMES_HOME is unset", () => {
+    delete process.env.HERMES_HOME;
+
+    expect(HermesagentMcp.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: expectedGlobalDir,
+      relativeFilePath: "config.yaml",
+    });
+  });
+
+  it("drops the .hermes prefix when HERMES_HOME names the profile root itself", () => {
+    process.env.HERMES_HOME = "/custom-hermes";
+
+    expect(HermesagentMcp.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: ".",
+      relativeFilePath: "config.yaml",
+    });
+  });
+});

src/features/permissions/hermesagent-permissions.test.ts

@@ -1,4 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
 
 import { parseSharedConfig } from "../shared/shared-config-gateway.js";
 import { HermesagentPermissions } from "./hermesagent-permissions.js";
@@ -341,3 +343,35 @@ security:
     expect(roundTripped).toEqual(canonical);
   });
 });
+
+describe("HermesagentPermissions global settable paths", () => {
+  // Pinned as literals rather than re-calling getHermesagentGlobalDir(), so the
+  // platform branch itself is asserted and not merely restated.
+  const expectedGlobalDir =
+    process.platform === "win32" ? join("AppData", "Local", "hermes") : ".hermes";
+
+  const originalHermesHome = process.env.HERMES_HOME;
+
+  afterEach(() => {
+    if (originalHermesHome === undefined) delete process.env.HERMES_HOME;
+    else process.env.HERMES_HOME = originalHermesHome;
+  });
+
+  it("anchors global paths on the platform profile directory when HERMES_HOME is unset", () => {
+    delete process.env.HERMES_HOME;
+
+    expect(HermesagentPermissions.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: expectedGlobalDir,
+      relativeFilePath: "config.yaml",
+    });
+  });
+
+  it("drops the .hermes prefix when HERMES_HOME names the profile root itself", () => {
+    process.env.HERMES_HOME = "/custom-hermes";
+
+    expect(HermesagentPermissions.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: ".",
+      relativeFilePath: "config.yaml",
+    });
+  });
+});

src/features/skills/hermesagent-skill.test.ts

@@ -1,3 +1,5 @@
+import { join } from "node:path";
+
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { HERMESAGENT_SKILLS_DIR_PATH } from "../../constants/hermesagent-paths.js";
@@ -257,3 +259,33 @@ describe("HermesagentSkill", () => {
     });
   });
 });
+
+describe("HermesagentSkill global settable paths", () => {
+  // Pinned as literals rather than re-calling getHermesagentGlobalDir(), so the
+  // platform branch itself is asserted and not merely restated.
+  const expectedGlobalDir =
+    process.platform === "win32" ? join("AppData", "Local", "hermes") : ".hermes";
+
+  const originalHermesHome = process.env.HERMES_HOME;
+
+  afterEach(() => {
+    if (originalHermesHome === undefined) delete process.env.HERMES_HOME;
+    else process.env.HERMES_HOME = originalHermesHome;
+  });
+
+  it("anchors global paths on the platform profile directory when HERMES_HOME is unset", () => {
+    delete process.env.HERMES_HOME;
+
+    expect(HermesagentSkill.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: join(expectedGlobalDir, "skills"),
+    });
+  });
+
+  it("drops the .hermes prefix when HERMES_HOME names the profile root itself", () => {
+    process.env.HERMES_HOME = "/custom-hermes";
+
+    expect(HermesagentSkill.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: "skills",
+    });
+  });
+});

src/features/subagents/hermesagent-subagent.test.ts

@@ -1,7 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test } from "vitest";
 
 import {
   HERMESAGENT_GLOBAL_DIR,
@@ -167,3 +167,33 @@ plugins:
     ]);
   });
 });
+
+describe("HermesagentSubagent global settable paths", () => {
+  // Pinned as literals rather than re-calling getHermesagentGlobalDir(), so the
+  // platform branch itself is asserted and not merely restated.
+  const expectedGlobalDir =
+    process.platform === "win32" ? join("AppData", "Local", "hermes") : ".hermes";
+
+  const originalHermesHome = process.env.HERMES_HOME;
+
+  afterEach(() => {
+    if (originalHermesHome === undefined) delete process.env.HERMES_HOME;
+    else process.env.HERMES_HOME = originalHermesHome;
+  });
+
+  test("anchors global paths on the platform profile directory when HERMES_HOME is unset", () => {
+    delete process.env.HERMES_HOME;
+
+    expect(HermesagentSubagent.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: join(expectedGlobalDir, "rulesync", "subagents"),
+    });
+  });
+
+  test("drops the .hermes prefix when HERMES_HOME names the profile root itself", () => {
+    process.env.HERMES_HOME = "/custom-hermes";
+
+    expect(HermesagentSubagent.getSettablePaths({ global: true })).toEqual({
+      relativeDirPath: join("rulesync", "subagents"),
+    });
+  });
+});

src/features/subagents/hermesagent-subagent.ts

@@ -218,6 +218,10 @@ export class HermesagentSubagent extends ToolSubagent {
     outputRoot,
     global = false,
   }: ToolSubagentsFromRulesyncSubagentsParams): HermesagentSubagent[] {
+    const pluginDirPath = getHermesagentRelativeDirPath({
+      global,
+      relativeDirPath: HERMESAGENT_RULESYNC_SUBAGENTS_PLUGIN_DIR_PATH,
+    });
     return [
       ...rulesyncSubagents.map((rulesyncSubagent) =>
         HermesagentSubagent.fromRulesyncSubagent({
@@ -228,20 +232,14 @@ export class HermesagentSubagent extends ToolSubagent {
         }),
       ),
       new HermesagentSubagent({
-        relativeDirPath: getHermesagentRelativeDirPath({
-          global,
-          relativeDirPath: HERMESAGENT_RULESYNC_SUBAGENTS_PLUGIN_DIR_PATH,
-        }),
+        relativeDirPath: pluginDirPath,
         relativeFilePath: basename(HERMESAGENT_RULESYNC_SUBAGENTS_PLUGIN_MANIFEST_PATH),
         fileContent: "",
         outputRoot,
         global,
       }),
       new HermesagentSubagent({
-        relativeDirPath: getHermesagentRelativeDirPath({
-          global,
-          relativeDirPath: HERMESAGENT_RULESYNC_SUBAGENTS_PLUGIN_DIR_PATH,
-        }),
+        relativeDirPath: pluginDirPath,
         relativeFilePath: basename(HERMESAGENT_RULESYNC_SUBAGENTS_PLUGIN_INIT_PATH),
         fileContent: "",
         outputRoot,