@juicesharp/rpiv-pi 1.12.0 → 1.13.0

package/README.md

@@ -223,6 +223,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 - **UI language** - run `/languages` to pick the locale for rpiv-* TUI strings, or pass `pi --locale <code>` at startup. Detection priority: flag → `~/.config/rpiv-i18n/locale.json` → `LANG` / `LC_ALL` → English. LLM-facing copy stays English by design
 - **Agent concurrency** - open the `/agents` overlay and tune `Settings → Max concurrency` to match your provider's rate limits. `@tintinweb/pi-subagents` owns this setting; rpiv-pi does not seed it.
 - **Agent profiles** - synced to `~/.pi/agent/agents/` from bundled defaults; refresh with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents).
+- **Non-default agent directory** - if you set `PI_CODING_AGENT_DIR` (e.g. `~/.config/pi/agent` for an XDG-style layout), rpiv-pi reads and writes the same `settings.json` Pi does — sibling detection, `/rpiv-setup`, and `/rpiv-update-agents` all follow the env var. Leading `~` is expanded.
 
 ## Uninstall
 

package/extensions/rpiv-core/package-checks.test.ts

@@ -3,12 +3,12 @@ import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { findMissingSiblings } from "./package-checks.js";
 import { SIBLINGS } from "./siblings.js";
-
-const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
+import { getPiAgentSettingsPath } from "./utils.js";
 
 function writeSettings(contents: unknown) {
-	mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
-	writeFileSync(SETTINGS_PATH, JSON.stringify(contents), "utf-8");
+	const settingsPath = getPiAgentSettingsPath();
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, JSON.stringify(contents), "utf-8");
 }
 
 describe("findMissingSiblings", () => {
@@ -17,8 +17,9 @@ describe("findMissingSiblings", () => {
 	});
 
 	it("returns all 7 siblings when JSON is invalid", () => {
-		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
-		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		const settingsPath = getPiAgentSettingsPath();
+		mkdirSync(dirname(settingsPath), { recursive: true });
+		writeFileSync(settingsPath, "{not json", "utf-8");
 		expect(findMissingSiblings()).toHaveLength(SIBLINGS.length);
 	});
 
@@ -56,4 +57,12 @@ describe("findMissingSiblings", () => {
 		});
 		expect(findMissingSiblings()).toEqual([]);
 	});
+
+	it("reads settings from PI_CODING_AGENT_DIR when configured", () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		writeSettings({
+			packages: SIBLINGS.map((s) => s.pkg.replace(/^npm:/, "")),
+		});
+		expect(findMissingSiblings()).toEqual([]);
+	});
 });

package/extensions/rpiv-core/package-checks.ts

@@ -1,5 +1,5 @@
 /**
- * Detect which SIBLINGS are installed by reading ~/.pi/agent/settings.json.
+ * Detect which SIBLINGS are installed by reading the active Pi settings file.
  * Pure utility — no ExtensionAPI.
  */
 
@@ -8,7 +8,7 @@ import { readPiAgentSettings } from "./utils.js";
 
 /**
  * Return the SIBLINGS not currently installed.
- * Reads ~/.pi/agent/settings.json once per call — callers that need both the
+ * Reads the active Pi settings file once per call — callers that need both the
  * full snapshot and the missing subset should call this once and filter.
  */
 export function findMissingSiblings(): SiblingPlugin[] {

package/extensions/rpiv-core/prune-legacy-siblings.test.ts

@@ -2,16 +2,24 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { findLegacySiblings, pruneLegacySiblings } from "./prune-legacy-siblings.js";
+import { getPiAgentSettingsPath } from "./utils.js";
 
-const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
+function writeSettingsRaw(raw: string): void {
+	const settingsPath = getPiAgentSettingsPath();
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, raw, "utf-8");
+}
 
 function writeSettings(contents: unknown): void {
-	mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
-	writeFileSync(SETTINGS_PATH, JSON.stringify(contents), "utf-8");
+	writeSettingsRaw(JSON.stringify(contents));
+}
+
+function readSettingsRaw(): string {
+	return readFileSync(getPiAgentSettingsPath(), "utf-8");
 }
 
 function readSettings(): unknown {
-	return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+	return JSON.parse(readSettingsRaw());
 }
 
 describe("pruneLegacySiblings", () => {
@@ -20,10 +28,9 @@ describe("pruneLegacySiblings", () => {
 	});
 
 	it("invalid JSON → pruned: [], file byte-exact unchanged", () => {
-		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
-		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		writeSettingsRaw("{not json");
 		expect(pruneLegacySiblings()).toEqual({ pruned: [] });
-		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe("{not json");
+		expect(readSettingsRaw()).toBe("{not json");
 	});
 
 	it("non-object top-level (array) → pruned: [], file unchanged", () => {
@@ -47,9 +54,9 @@ describe("pruneLegacySiblings", () => {
 		writeSettings({
 			packages: ["npm:pi-perplexity", "npm:@juicesharp/rpiv-todo", "npm:@tintinweb/pi-subagents"],
 		});
-		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		const before = readSettingsRaw();
 		expect(pruneLegacySiblings()).toEqual({ pruned: [] });
-		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
+		expect(readSettingsRaw()).toBe(before);
 	});
 
 	it("legacy-only: removes pi-subagents (nicobailon fork), preserves other top-level keys", () => {
@@ -93,6 +100,15 @@ describe("pruneLegacySiblings", () => {
 		});
 	});
 
+	it("prunes settings from PI_CODING_AGENT_DIR when configured", () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		writeSettings({
+			packages: ["npm:pi-subagents"],
+		});
+		expect(pruneLegacySiblings().pruned).toEqual(["npm:pi-subagents"]);
+		expect(readSettings()).toEqual({ packages: [] });
+	});
+
 	it("idempotent: second call after prune is a no-op", () => {
 		writeSettings({
 			packages: ["npm:pi-subagents"],
@@ -115,8 +131,7 @@ describe("findLegacySiblings (read-only scan)", () => {
 	});
 
 	it("invalid JSON → []", () => {
-		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
-		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		writeSettingsRaw("{not json");
 		expect(findLegacySiblings()).toEqual([]);
 	});
 
@@ -147,16 +162,22 @@ describe("findLegacySiblings (read-only scan)", () => {
 			defaultProvider: "zai",
 			packages: ["npm:pi-subagents", "npm:@juicesharp/rpiv-todo"],
 		});
-		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		const before = readSettingsRaw();
+		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
+		expect(readSettingsRaw()).toBe(before);
+	});
+
+	it("reads settings from PI_CODING_AGENT_DIR when configured", () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		writeSettings({ packages: ["npm:pi-subagents"] });
 		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
-		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
 	});
 
 	it("idempotent: repeat call returns the same list and does not mutate", () => {
 		writeSettings({ packages: ["npm:pi-subagents"] });
-		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		const before = readSettingsRaw();
 		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
 		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
-		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
+		expect(readSettingsRaw()).toBe(before);
 	});
 });

package/extensions/rpiv-core/prune-legacy-siblings.ts

@@ -1,6 +1,6 @@
 /**
  * Detect + remove deprecated sibling package entries from
- * ~/.pi/agent/settings.json.
+ * the active Pi agent settings file.
  *
  * Split into two phases so /rpiv-setup can preview pending changes in the
  * confirmation dialog and apply the mutation only after the user agrees:
@@ -23,7 +23,7 @@
 
 import { writeFileSync } from "node:fs";
 import { LEGACY_SIBLINGS } from "./siblings.js";
-import { PI_AGENT_SETTINGS, readPiAgentSettings } from "./utils.js";
+import { getPiAgentSettingsPath, readPiAgentSettings } from "./utils.js";
 
 export interface PruneLegacySiblingsResult {
 	/** settings.json `packages[]` entries that were removed (empty = no-op). */
@@ -65,7 +65,7 @@ export function pruneLegacySiblings(): PruneLegacySiblingsResult {
 
 	parsed.settings.packages = kept;
 	try {
-		writeFileSync(PI_AGENT_SETTINGS, `${JSON.stringify(parsed.settings, null, 2)}\n`, "utf-8");
+		writeFileSync(getPiAgentSettingsPath(), `${JSON.stringify(parsed.settings, null, 2)}\n`, "utf-8");
 	} catch {
 		return { pruned: [] };
 	}

package/extensions/rpiv-core/setup-command.test.ts

@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { createMockCtx, createMockPi } from "@juicesharp/rpiv-test-utils";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -85,6 +86,18 @@ describe("/rpiv-setup — pre-confirm read-only contract", () => {
 		expect(confirmCall[1]).toContain("npm:pi-subagents");
 	});
 
+	it("shows the PI_CODING_AGENT_DIR settings path in the confirmation body", async () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		vi.mocked(findMissingSiblings).mockReturnValue([]);
+		vi.mocked(findLegacySiblings).mockReturnValue(["npm:pi-subagents"]);
+		const { pi, captured } = createMockPi();
+		registerSetupCommand(pi);
+		const ctx = createMockCtx({ hasUI: true });
+		await captured.commands.get("rpiv-setup")?.handler("", ctx as never);
+		const confirmCall = (ctx.ui.confirm as ReturnType<typeof vi.fn>).mock.calls[0]!;
+		expect(confirmCall[1]).toContain(join(process.env.HOME!, ".config", "pi", "agent", "settings.json"));
+	});
+
 	it("includes pending installs in the confirmation body", async () => {
 		vi.mocked(findMissingSiblings).mockReturnValue([{ pkg: "npm:@x/a", matches: /./, provides: "A" }]);
 		vi.mocked(findLegacySiblings).mockReturnValue([]);

package/extensions/rpiv-core/setup-command.ts

@@ -1,5 +1,5 @@
 /**
- * /rpiv-setup — installs any SIBLINGS not present in ~/.pi/agent/settings.json
+ * /rpiv-setup — installs any SIBLINGS not present in the active Pi settings file
  * and prunes deprecated entries (e.g. the unscoped `npm:pi-subagents` from
  * the rpiv-pi 0.12.x → 0.14.0 line). Both mutations are previewed in the
  * confirmation dialog and only executed after the user agrees.
@@ -13,7 +13,7 @@ import { findMissingSiblings } from "./package-checks.js";
 import { spawnPiInstall } from "./pi-installer.js";
 import { findLegacySiblings, pruneLegacySiblings } from "./prune-legacy-siblings.js";
 import type { SiblingPlugin } from "./siblings.js";
-import { toErrorMessage } from "./utils.js";
+import { getPiAgentSettingsPath, toErrorMessage } from "./utils.js";
 
 const INSTALL_TIMEOUT_MS = 120_000;
 const STDERR_SNIPPET_CHARS = 300;
@@ -43,12 +43,13 @@ function buildConfirmBody(missing: SiblingPlugin[], legacyEntries: string[]): st
 		for (const m of missing) lines.push(`  • ${m.pkg}  (required — provides ${m.provides})`);
 		lines.push("");
 	}
+	const settingsPath = getPiAgentSettingsPath();
 	if (legacyEntries.length > 0) {
-		lines.push("Remove from `~/.pi/agent/settings.json` (deprecated):");
+		lines.push(`Remove from \`${settingsPath}\` (deprecated):`);
 		for (const entry of legacyEntries) lines.push(`  • ${entry}`);
 		lines.push("");
 	}
-	lines.push("Your `~/.pi/agent/settings.json` will be updated. Proceed?");
+	lines.push(`Your \`${settingsPath}\` will be updated. Proceed?`);
 	return lines.join("\n");
 }
 

package/extensions/rpiv-core/siblings.ts

@@ -6,14 +6,14 @@
  * /rpiv-setup installer (setup-command.ts). Add a sibling here and every
  * consumer picks it up automatically.
  *
- * Detection is filesystem-based via a regex over ~/.pi/agent/settings.json
+ * Detection is filesystem-based via a regex over the active Pi settings file
  * — no runtime import of sibling packages (keeps rpiv-core pure-orchestrator).
  */
 
 export interface SiblingPlugin {
 	/** Install spec passed to `pi install`. Prefixed with `npm:` for Pi's installer. */
 	readonly pkg: string;
-	/** Case-insensitive regex that matches the package in ~/.pi/agent/settings.json. */
+	/** Case-insensitive regex that matches the package in settings.json. */
 	readonly matches: RegExp;
 	/** What the sibling provides — shown in /rpiv-setup confirmation and reports. */
 	readonly provides: string;
@@ -59,7 +59,7 @@ export const SIBLINGS: readonly SiblingPlugin[] = [
 
 /**
  * Deprecated sibling packages that `/rpiv-setup` actively prunes from
- * ~/.pi/agent/settings.json (so upgraders don't end up with superseded
+ * the active Pi settings file (so upgraders don't end up with superseded
  * libraries loaded alongside their replacements). Single source of truth
  * for `prune-legacy-siblings.ts`.
  */

package/extensions/rpiv-core/utils.test.ts

@@ -1,15 +1,21 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { isPlainObject, PI_AGENT_SETTINGS, readPiAgentSettings, toErrorMessage } from "./utils.js";
-
-function writeSettingsRaw(raw: string): void {
-	mkdirSync(dirname(PI_AGENT_SETTINGS), { recursive: true });
-	writeFileSync(PI_AGENT_SETTINGS, raw, "utf-8");
+import {
+	getPiAgentSettingsPath,
+	isPlainObject,
+	PI_AGENT_SETTINGS,
+	readPiAgentSettings,
+	toErrorMessage,
+} from "./utils.js";
+
+function writeSettingsRaw(raw: string, path = getPiAgentSettingsPath()): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, raw, "utf-8");
 }
 
-function writeSettings(contents: unknown): void {
-	writeSettingsRaw(JSON.stringify(contents));
+function writeSettings(contents: unknown, path = getPiAgentSettingsPath()): void {
+	writeSettingsRaw(JSON.stringify(contents), path);
 }
 
 describe("isPlainObject", () => {
@@ -65,6 +71,22 @@ describe("toErrorMessage", () => {
 	});
 });
 
+describe("getPiAgentSettingsPath", () => {
+	it("uses ~/.pi/agent/settings.json when PI_CODING_AGENT_DIR is unset", () => {
+		expect(getPiAgentSettingsPath()).toBe(PI_AGENT_SETTINGS);
+	});
+
+	it("uses PI_CODING_AGENT_DIR/settings.json when configured", () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		expect(getPiAgentSettingsPath()).toBe(join(process.env.HOME!, ".config", "pi", "agent", "settings.json"));
+	});
+
+	it("expands a leading ~ in PI_CODING_AGENT_DIR", () => {
+		process.env.PI_CODING_AGENT_DIR = "~/.config/pi/agent";
+		expect(getPiAgentSettingsPath()).toBe(join(process.env.HOME!, ".config", "pi", "agent", "settings.json"));
+	});
+});
+
 describe("readPiAgentSettings", () => {
 	it("returns undefined when the settings file is missing", () => {
 		rmSync(PI_AGENT_SETTINGS, { force: true });
@@ -105,6 +127,12 @@ describe("readPiAgentSettings", () => {
 		});
 	});
 
+	it("reads from PI_CODING_AGENT_DIR/settings.json when configured", () => {
+		process.env.PI_CODING_AGENT_DIR = join(process.env.HOME!, ".config", "pi", "agent");
+		writeSettings({ packages: ["npm:@juicesharp/rpiv-todo"] });
+		expect(readPiAgentSettings()?.packages).toEqual(["npm:@juicesharp/rpiv-todo"]);
+	});
+
 	it("preserves non-string entries inside packages (caller responsibility to filter)", () => {
 		writeSettings({ packages: [null, 42, "npm:pi-subagents"] });
 		const result = readPiAgentSettings();

package/extensions/rpiv-core/utils.ts

@@ -7,14 +7,24 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 // ---------------------------------------------------------------------------
 // PI Agent Settings path
 // ---------------------------------------------------------------------------
 
-/** Path to the Pi agent settings file. Shared by package-checks and prune-legacy-siblings. */
+/** Default Pi agent settings path when PI_CODING_AGENT_DIR is not configured. */
 export const PI_AGENT_SETTINGS = join(homedir(), ".pi", "agent", "settings.json");
 
+/**
+ * Resolve the active Pi agent settings file. Delegates the agent-dir lookup to
+ * Pi's `getAgentDir()` so PI_CODING_AGENT_DIR handling (including tilde
+ * expansion) stays in one place across rpiv-pi and Pi itself.
+ */
+export function getPiAgentSettingsPath(): string {
+	return join(getAgentDir(), "settings.json");
+}
+
 // ---------------------------------------------------------------------------
 // Type guards
 // ---------------------------------------------------------------------------
@@ -48,15 +58,16 @@ interface PiAgentSettingsResult {
 }
 
 /**
- * Read and parse ~/.pi/agent/settings.json.
+ * Read and parse the active Pi agent settings file.
  * Returns undefined if the file is missing, has invalid JSON, or is not a plain object
  * with a packages array. Fail-soft — never throws.
  */
 export function readPiAgentSettings(): PiAgentSettingsResult | undefined {
-	if (!existsSync(PI_AGENT_SETTINGS)) return undefined;
+	const settingsPath = getPiAgentSettingsPath();
+	if (!existsSync(settingsPath)) return undefined;
 	let parsed: unknown;
 	try {
-		parsed = JSON.parse(readFileSync(PI_AGENT_SETTINGS, "utf-8"));
+		parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
 	} catch {
 		return undefined;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",