@mattstack/rt-client 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
+export { guardTestDaemonEnv } from "./test-isolation.ts";
 export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, reconcilerStatus, reconcilerClear, gateOpen, gateAsk, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
 export { GATE_FORM_OPTION_CAP, gatePresentation } from "./gate-presentation.ts";

package/dist/index.js

@@ -2,14 +2,52 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/transport.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+
+// src/test-isolation.ts
 import { homedir } from "os";
 import { join } from "path";
+function parseForbidSocks(raw) {
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.some((path) => typeof path !== "string")) {
+    throw new Error("rt-client: RT_TEST_FORBID_SOCKS must be a JSON string array of socket paths");
+  }
+  return parsed;
+}
+function guardTestDaemonEnv(env = process.env) {
+  const forbidden = new Set;
+  if (env.RT_TEST_FORBID_SOCKS) {
+    for (const path of parseForbidSocks(env.RT_TEST_FORBID_SOCKS))
+      forbidden.add(path);
+  }
+  if (env.RT_DAEMON_SOCK)
+    forbidden.add(env.RT_DAEMON_SOCK);
+  if (env.RT_APP_SOCKET)
+    forbidden.add(env.RT_APP_SOCKET);
+  forbidden.add(join(env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock"));
+  delete env.RT_DAEMON_SOCK;
+  delete env.RT_APP_SOCKET;
+  env.RT_TEST_FORBID_SOCKS = JSON.stringify([...forbidden]);
+}
+
+// src/transport.ts
 function defaultSock() {
-  return process.env.RT_DAEMON_SOCK || join(process.env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock");
+  return process.env.RT_DAEMON_SOCK || join2(process.env.HOME ?? homedir2(), ".mattstack", "rt", "rt.sock");
 }
 var DEFAULT_SOCK = defaultSock();
+function assertSockNotForbidden(cmd, sockPath) {
+  const raw = process.env.RT_TEST_FORBID_SOCKS;
+  if (!raw)
+    return;
+  const forbidden = parseForbidSocks(raw);
+  if (forbidden.includes(sockPath)) {
+    throw new Error(`rt-client: refusing "${cmd}" at forbidden socket ${sockPath}: RT_TEST_FORBID_SOCKS marks it as a live daemon socket, so this dispatch would have escaped test isolation`);
+  }
+}
 async function rtCommand(cmd, payload, opts = {}) {
   const sockPath = opts.sockPath ?? defaultSock();
+  assertSockNotForbidden(cmd, sockPath);
   try {
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,
@@ -691,10 +729,10 @@ async function daemonHealth(opts = {}) {
 }
 // src/repos.ts
 import { existsSync, readFileSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname, join as join2 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname, join as join3 } from "path";
 function defaultReposJsonPath() {
-  return join2(homedir2(), ".mattstack", "rt", "repos.json");
+  return join3(homedir3(), ".mattstack", "rt", "repos.json");
 }
 function loadBunSqliteDatabase() {
   try {
@@ -746,7 +784,7 @@ function repoNameFromJson(repoPath, reposJsonPath) {
 }
 function repoNameForPath(repoPath, reposJsonPath) {
   const jsonPath = reposJsonPath ?? defaultReposJsonPath();
-  const dbPath = join2(dirname(jsonPath), "state.db");
+  const dbPath = join3(dirname(jsonPath), "state.db");
   const fromDb = repoNameFromStateDb(repoPath, dbPath);
   if (fromDb !== null)
     return fromDb;
@@ -826,33 +864,33 @@ function formatPaneRef(paneId, server) {
   return BG_PREFIX + paneId;
 }
 // src/settings/resolve.ts
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
+import { homedir as homedir5 } from "os";
+import { join as join6 } from "path";
 
 // src/settings/paths.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { homedir as homedir3, hostname } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir4, hostname } from "os";
+import { join as join4 } from "path";
 function home() {
-  return process.env.HOME ?? homedir3();
+  return process.env.HOME ?? homedir4();
 }
 function userSettingsPath() {
-  return join3(home(), ".mattstack", "user", "settings.user.jsonc");
+  return join4(home(), ".mattstack", "user", "settings.user.jsonc");
 }
 function teamSettingsPath(team) {
-  return join3(teamsDir(), team, "mattstack", "settings.team.jsonc");
+  return join4(teamsDir(), team, "mattstack", "settings.team.jsonc");
 }
 function teamLocalPath(team) {
-  return join3(home(), ".mattstack", "rt", "teams", `${team}.json`);
+  return join4(home(), ".mattstack", "rt", "teams", `${team}.json`);
 }
 function machineSettingsPath() {
-  return join3(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
+  return join4(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
 }
 function teamsDir() {
-  return join3(home(), ".mattstack", "teams");
+  return join4(home(), ".mattstack", "teams");
 }
 function machineKey() {
-  const override = join3(home(), ".mattstack", "machine-key");
+  const override = join4(home(), ".mattstack", "machine-key");
   try {
     const v = readFileSync2(override, "utf8").trim();
     if (isSafeMachineKeySegment(v))
@@ -1591,7 +1629,7 @@ function findPathGuardViolation(value, guardFields) {
 // src/settings/stores.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3, statSync } from "fs";
 import { parse } from "jsonc-parser";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 var EMPTY_STORE = (file, exists) => ({
   global: {},
   repos: {},
@@ -1638,13 +1676,13 @@ function listTeams() {
   const teams = [];
   for (const entry of entries) {
     try {
-      const isDir = entry.isDirectory() || entry.isSymbolicLink() && statSync(join4(dir, entry.name)).isDirectory();
+      const isDir = entry.isDirectory() || entry.isSymbolicLink() && statSync(join5(dir, entry.name)).isDirectory();
       if (!isDir)
         continue;
       if (existsSync2(teamSettingsPath(entry.name)))
         teams.push(entry.name);
     } catch (err) {
-      console.warn(`rt: skipping unreadable teams entry ${join4(dir, entry.name)}: ${err.message}`);
+      console.warn(`rt: skipping unreadable teams entry ${join5(dir, entry.name)}: ${err.message}`);
     }
   }
   return teams;
@@ -1693,7 +1731,7 @@ function teamPath(teamsDir2, name) {
   if (name.includes("/") || name.includes("\\") || name.includes("..")) {
     throw new Error(`rt: cannot expand \${team:${name}} — a team name must be a single directory segment (no "/", "\\" or "..")`);
   }
-  return join5(teamsDir2, name);
+  return join6(teamsDir2, name);
 }
 function required(value, name, needs) {
   if (value === undefined || value === "") {
@@ -1868,7 +1906,7 @@ function expandCtxFrom(opts) {
   return {
     repoRoot: opts.expandCtx?.repoRoot,
     worktree: opts.expandCtx?.worktree,
-    home: process.env.HOME ?? homedir4(),
+    home: process.env.HOME ?? homedir5(),
     teamsDir: teamsDir()
   };
 }
@@ -2409,6 +2447,7 @@ export {
   herdAttend,
   herdAsk,
   herdAnswer,
+  guardTestDaemonEnv,
   getSetting,
   getRun,
   getDef,

package/dist/test-isolation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Strict by design: a JSON string is iterable and has .includes(), so an
+ * unvalidated parse would let a malformed value corrupt the merge here or
+ * silently disarm the transport guard. Anything but a string array throws.
+ */
+export declare function parseForbidSocks(raw: string): string[];
+export declare function guardTestDaemonEnv(env?: NodeJS.ProcessEnv): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -1,5 +1,6 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
+export { guardTestDaemonEnv } from "./test-isolation.ts";
 
 export {
   readProjectMRs,

package/src/test-isolation.ts

@@ -0,0 +1,36 @@
+/**
+ * Test-run isolation for suites that repoint HOME at a throwaway directory.
+ * An ambient RT_DAEMON_SOCK (herdr panes, agent shells) routes rtCommand at
+ * a live daemon over the top of the fake HOME, so a repointed HOME alone is
+ * not isolation. A test preload calls this BEFORE repointing HOME: it strips
+ * the live pointers from the env and arms RT_TEST_FORBID_SOCKS, the list of
+ * sockets rtCommand refuses to dispatch at (transport.ts).
+ */
+import { homedir } from "os";
+import { join } from "path";
+
+/**
+ * Strict by design: a JSON string is iterable and has .includes(), so an
+ * unvalidated parse would let a malformed value corrupt the merge here or
+ * silently disarm the transport guard. Anything but a string array throws.
+ */
+export function parseForbidSocks(raw: string): string[] {
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.some((path) => typeof path !== "string")) {
+    throw new Error("rt-client: RT_TEST_FORBID_SOCKS must be a JSON string array of socket paths");
+  }
+  return parsed;
+}
+
+export function guardTestDaemonEnv(env: NodeJS.ProcessEnv = process.env): void {
+  const forbidden = new Set<string>();
+  if (env.RT_TEST_FORBID_SOCKS) {
+    for (const path of parseForbidSocks(env.RT_TEST_FORBID_SOCKS)) forbidden.add(path);
+  }
+  if (env.RT_DAEMON_SOCK) forbidden.add(env.RT_DAEMON_SOCK);
+  if (env.RT_APP_SOCKET) forbidden.add(env.RT_APP_SOCKET);
+  forbidden.add(join(env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock"));
+  delete env.RT_DAEMON_SOCK;
+  delete env.RT_APP_SOCKET;
+  env.RT_TEST_FORBID_SOCKS = JSON.stringify([...forbidden]);
+}

package/src/transport.ts

@@ -9,6 +9,7 @@
  */
 import { homedir } from "os";
 import { join } from "path";
+import { parseForbidSocks } from "./test-isolation.ts";
 
 export interface RtResponse<T = unknown> {
   ok: boolean;
@@ -56,12 +57,31 @@ function defaultSock(): string {
  */
 export const DEFAULT_SOCK = defaultSock();
 
+/**
+ * The one exception to the never-throws contract below: when a test preload
+ * has armed RT_TEST_FORBID_SOCKS (see test-isolation.ts), dispatching at a
+ * listed socket throws instead of degrading. A degrade envelope could be
+ * tolerated by the calling test; escaping isolation must fail the run loudly.
+ * A malformed list throws too rather than silently disarming the guard.
+ */
+function assertSockNotForbidden(cmd: string, sockPath: string): void {
+  const raw = process.env.RT_TEST_FORBID_SOCKS;
+  if (!raw) return;
+  const forbidden = parseForbidSocks(raw);
+  if (forbidden.includes(sockPath)) {
+    throw new Error(
+      `rt-client: refusing "${cmd}" at forbidden socket ${sockPath}: RT_TEST_FORBID_SOCKS marks it as a live daemon socket, so this dispatch would have escaped test isolation`,
+    );
+  }
+}
+
 export async function rtCommand<T = unknown>(
   cmd: string,
   payload: Record<string, unknown>,
   opts: { sockPath?: string; timeoutMs?: number } = {},
 ): Promise<RtResponse<T>> {
   const sockPath = opts.sockPath ?? defaultSock();
+  assertSockNotForbidden(cmd, sockPath);
   try {
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,