@mattstack/rt-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Goodwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @mattstack/rt-client
+
+Typed client for the [rt](https://rt.cool) daemon.
+
+rt keeps the per-repo state a dev environment needs: worktrees, assigned ports,
+tokens, dev servers, and a live event relay. This package is how other programs
+read and drive that state without shelling out to the CLI and parsing text.
+
+```bash
+bun add @mattstack/rt-client
+```
+
+```ts
+import { rtCommand, readProjectMRs } from '@mattstack/rt-client';
+
+const repos = await rtCommand(['repos', 'list']);
+const mrs = await readProjectMRs('group/repo');
+```
+
+Requires a running rt daemon. Install rt with `brew install m4ttheweric/tap/rt`,
+then `rt verify`.
+
+`@mattstack/glance` is a peer dependency: rt-client returns glance's forge types
+so merge request shapes stay identical across rt, gitq, and mr-board.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import type { RtResponse, RtClientOptions } from "./transport.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData } from "./commands.ts";
+/**
+ * One repo's project open-MR store. A cold repo forces a full paginated sync
+ * on the daemon side when maxAgeMs demands it, which can run tens of seconds
+ * on a big project -- hence the long timeout.
+ *
+ * `demand` tells the daemon what this caller needs covered (client id, the
+ * authors it cares about, when it declared that need), so the daemon can
+ * size the sync to actually cover it rather than trusting the store's
+ * self-reported source.
+ */
+export declare function readProjectMRs(repoName: string, maxAgeMs?: number, opts?: RtClientOptions, demand?: DemandDecl): Promise<RtResponse<ProjectMRsData>>;
+export declare function readDiscussions(repoName: string, iid: number, opts?: RtClientOptions): Promise<RtResponse<DiscussionsData>>;
+export declare function readMrsByBranch(repoName: string, branches: string[], opts?: RtClientOptions): Promise<RtResponse<MrByBranchData>>;

package/dist/commands.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The typed command catalog for the rt daemon: one entry per command name,
+ * pairing its payload shape with its response data shape. `client.ts` builds
+ * its functions against this map so a new command only needs an entry here
+ * plus one function, never a change to the transport itself.
+ */
+import type { PullRequest, MRDetail } from "@mattstack/glance";
+export type Discussion = MRDetail["discussions"][number];
+/** What a caller declares it needs, so the daemon can size the sync to cover it. */
+export interface DemandDecl {
+    client: string;
+    authors: string[];
+    declaredAt: number;
+}
+export interface ProjectMRsScope {
+    authors: string[];
+    windowDays: number;
+    uncovered: string[];
+}
+export interface ProjectMRsData {
+    mrs: Record<string, {
+        pr: PullRequest;
+        fetchedAt: number;
+    }>;
+    listSyncedAt: number;
+    source: "poll" | "events" | "mutation";
+    syncedAt: number;
+    scope?: ProjectMRsScope;
+}
+export interface DiscussionsData {
+    discussions: Discussion[];
+    fetchedAt: number;
+    stale?: boolean;
+}
+export interface MrByBranchEntry {
+    pr: PullRequest;
+    source: "store" | "forge";
+}
+export interface MrByBranchData {
+    byBranch: Record<string, MrByBranchEntry | null>;
+    syncedAt: number;
+}
+export interface Commands {
+    "project-mrs:read": {
+        payload: {
+            repoName: string;
+            maxAgeMs?: number;
+            demand?: DemandDecl;
+        };
+        data: ProjectMRsData;
+    };
+    "discussions:read": {
+        payload: {
+            repoName: string;
+            iid: number;
+        };
+        data: DiscussionsData;
+    };
+    "mr:by-branch": {
+        payload: {
+            repoName: string;
+            branches: string[];
+        };
+        data: MrByBranchData;
+    };
+}
+export type CommandName = keyof Commands;
+export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
+export type { RtResponse, RtClientOptions } from "./transport.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch } from "./client.ts";
+export { COMMAND_NAMES } from "./commands.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, Commands, CommandName, } from "./commands.ts";
+export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
+export type { RelayEventType } from "./relay.ts";
+export { repoNameForPath } from "./repos.ts";

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/transport.ts
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_SOCK = join(homedir(), ".rt", "rt.sock");
+async function rtCommand(cmd, payload, opts = {}) {
+  const sockPath = opts.sockPath ?? DEFAULT_SOCK;
+  try {
+    const res = await fetch(`http://localhost/${cmd}`, {
+      unix: sockPath,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 15000)
+    });
+    return await res.json();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `rt daemon unreachable at ${sockPath}: ${msg}` };
+  }
+}
+// src/client.ts
+function readProjectMRs(repoName, maxAgeMs, opts = {}, demand) {
+  const payload = { repoName };
+  if (maxAgeMs !== undefined)
+    payload.maxAgeMs = maxAgeMs;
+  if (demand !== undefined)
+    payload.demand = demand;
+  return rtCommand("project-mrs:read", payload, { sockPath: opts.sockPath, timeoutMs: 90000 });
+}
+function readDiscussions(repoName, iid, opts = {}) {
+  return rtCommand("discussions:read", { repoName, iid }, { sockPath: opts.sockPath, timeoutMs: 30000 });
+}
+function readMrsByBranch(repoName, branches, opts = {}) {
+  return rtCommand("mr:by-branch", { repoName, branches }, { sockPath: opts.sockPath, timeoutMs: 60000 });
+}
+// src/commands.ts
+var COMMAND_NAMES = ["project-mrs:read", "discussions:read", "mr:by-branch"];
+// src/relay.ts
+var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
+function subscribe(onEvent, opts = {}) {
+  const url = opts.wsUrl ?? DEFAULT_WS_URL;
+  let ws = null;
+  let stopped = false;
+  let attempt = 0;
+  let timer;
+  const connect = () => {
+    if (stopped)
+      return;
+    ws = new WebSocket(url);
+    ws.onopen = () => {
+      attempt = 0;
+    };
+    ws.onmessage = (ev) => {
+      try {
+        const frame = JSON.parse(String(ev.data));
+        if (typeof frame.type === "string")
+          onEvent(frame.type, frame.data);
+      } catch {}
+    };
+    ws.onclose = () => {
+      if (stopped)
+        return;
+      const delay = Math.min(30000, 1000 * 2 ** attempt++);
+      timer = setTimeout(connect, delay);
+    };
+    ws.onerror = () => {
+      try {
+        ws?.close();
+      } catch {}
+    };
+  };
+  connect();
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+    try {
+      ws?.close();
+    } catch {}
+  };
+}
+// src/repos.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+function defaultReposJsonPath() {
+  return join2(homedir2(), ".rt", "repos.json");
+}
+function repoNameForPath(repoPath, reposJsonPath) {
+  const path = reposJsonPath ?? defaultReposJsonPath();
+  try {
+    if (!existsSync(path))
+      return null;
+    const raw = readFileSync(path, "utf8");
+    const index = JSON.parse(raw);
+    for (const [repoName, value] of Object.entries(index)) {
+      if (value === repoPath)
+        return repoName;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+export {
+  subscribe,
+  rtCommand,
+  repoNameForPath,
+  readProjectMRs,
+  readMrsByBranch,
+  readDiscussions,
+  DEFAULT_WS_URL,
+  DEFAULT_SOCK,
+  COMMAND_NAMES
+};

package/dist/relay.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Push events from the rt daemon's WebSocket relay (127.0.0.1:9401),
+ * `{ type, data, timestamp }` frames.
+ *
+ * Ported verbatim from mr-board's src/rt-client.ts.
+ */
+import type { RtClientOptions } from "./transport.ts";
+export type RelayEventType = "project-mrs" | "discussions:update" | "discussions:new-comments" | "mr:status" | (string & {});
+export declare const DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
+/**
+ * Subscribe to the daemon's broadcast channel. Reconnects with capped
+ * exponential backoff (1s to 30s) until the returned stop function runs;
+ * the daemon being down just means silence, never a crash.
+ */
+export declare function subscribe(onEvent: (type: RelayEventType, data: unknown) => void, opts?: RtClientOptions): () => void;

package/dist/repos.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Exact-match lookup: returns the repo name whose recorded path equals
+ * `repoPath`, or null if the file is missing, corrupt, or has no match.
+ * Never throws -- a resolution failure just means the caller falls back to
+ * whatever it had before (an unqualified path, a prompt, etc).
+ */
+export declare function repoNameForPath(repoPath: string, reposJsonPath?: string): string | null;

package/dist/transport.d.ts

@@ -0,0 +1,14 @@
+export interface RtResponse<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+}
+export interface RtClientOptions {
+    sockPath?: string;
+    wsUrl?: string;
+}
+export declare const DEFAULT_SOCK: string;
+export declare function rtCommand<T = unknown>(cmd: string, payload: Record<string, unknown>, opts?: {
+    sockPath?: string;
+    timeoutMs?: number;
+}): Promise<RtResponse<T>>;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mattstack/rt-client",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./test/fake-daemon.ts": "./test/fake-daemon.ts"
+  },
+  "peerDependencies": {
+    "@mattstack/glance": ">=0.13.0"
+  },
+  "description": "Typed client for the rt daemon: repos, worktrees, ports, tokens, and the event relay",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m4ttstack/rt.git",
+    "directory": "packages/rt-client"
+  },
+  "homepage": "https://rt.cool",
+  "bugs": {
+    "url": "https://github.com/m4ttstack/rt/issues"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,54 @@
+/**
+ * Typed reads against the rt daemon's command surface (see commands.ts).
+ * Every function degrades to `{ ok: false, error }` instead of throwing,
+ * inherited from rtCommand -- callers surface daemon-down verbatim.
+ */
+import { rtCommand } from "./transport.ts";
+import type { RtResponse, RtClientOptions } from "./transport.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData } from "./commands.ts";
+
+/**
+ * One repo's project open-MR store. A cold repo forces a full paginated sync
+ * on the daemon side when maxAgeMs demands it, which can run tens of seconds
+ * on a big project -- hence the long timeout.
+ *
+ * `demand` tells the daemon what this caller needs covered (client id, the
+ * authors it cares about, when it declared that need), so the daemon can
+ * size the sync to actually cover it rather than trusting the store's
+ * self-reported source.
+ */
+export function readProjectMRs(
+  repoName: string,
+  maxAgeMs?: number,
+  opts: RtClientOptions = {},
+  demand?: DemandDecl,
+): Promise<RtResponse<ProjectMRsData>> {
+  const payload: Record<string, unknown> = { repoName };
+  if (maxAgeMs !== undefined) payload.maxAgeMs = maxAgeMs;
+  if (demand !== undefined) payload.demand = demand;
+  return rtCommand<ProjectMRsData>("project-mrs:read", payload, { sockPath: opts.sockPath, timeoutMs: 90_000 });
+}
+
+export function readDiscussions(
+  repoName: string,
+  iid: number,
+  opts: RtClientOptions = {},
+): Promise<RtResponse<DiscussionsData>> {
+  return rtCommand<DiscussionsData>(
+    "discussions:read",
+    { repoName, iid },
+    { sockPath: opts.sockPath, timeoutMs: 30_000 },
+  );
+}
+
+export function readMrsByBranch(
+  repoName: string,
+  branches: string[],
+  opts: RtClientOptions = {},
+): Promise<RtResponse<MrByBranchData>> {
+  return rtCommand<MrByBranchData>(
+    "mr:by-branch",
+    { repoName, branches },
+    { sockPath: opts.sockPath, timeoutMs: 60_000 },
+  );
+}

package/src/commands.ts

@@ -0,0 +1,56 @@
+/**
+ * The typed command catalog for the rt daemon: one entry per command name,
+ * pairing its payload shape with its response data shape. `client.ts` builds
+ * its functions against this map so a new command only needs an entry here
+ * plus one function, never a change to the transport itself.
+ */
+import type { PullRequest, MRDetail } from "@mattstack/glance";
+
+export type Discussion = MRDetail["discussions"][number];
+
+/** What a caller declares it needs, so the daemon can size the sync to cover it. */
+export interface DemandDecl {
+  client: string;
+  authors: string[];
+  declaredAt: number;
+}
+
+export interface ProjectMRsScope {
+  authors: string[];
+  windowDays: number;
+  uncovered: string[];
+}
+
+export interface ProjectMRsData {
+  mrs: Record<string, { pr: PullRequest; fetchedAt: number }>;
+  listSyncedAt: number;
+  source: "poll" | "events" | "mutation";
+  syncedAt: number;
+  scope?: ProjectMRsScope;
+}
+
+export interface DiscussionsData {
+  discussions: Discussion[];
+  fetchedAt: number;
+  stale?: boolean;
+}
+
+export interface MrByBranchEntry {
+  pr: PullRequest;
+  source: "store" | "forge";
+}
+
+export interface MrByBranchData {
+  byBranch: Record<string, MrByBranchEntry | null>;
+  syncedAt: number;
+}
+
+export interface Commands {
+  "project-mrs:read": { payload: { repoName: string; maxAgeMs?: number; demand?: DemandDecl }; data: ProjectMRsData };
+  "discussions:read": { payload: { repoName: string; iid: number }; data: DiscussionsData };
+  "mr:by-branch": { payload: { repoName: string; branches: string[] }; data: MrByBranchData };
+}
+
+export type CommandName = keyof Commands;
+
+export const COMMAND_NAMES: readonly CommandName[] = ["project-mrs:read", "discussions:read", "mr:by-branch"];

package/src/index.ts

@@ -0,0 +1,22 @@
+export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
+export type { RtResponse, RtClientOptions } from "./transport.ts";
+
+export { readProjectMRs, readDiscussions, readMrsByBranch } from "./client.ts";
+
+export { COMMAND_NAMES } from "./commands.ts";
+export type {
+  Discussion,
+  DemandDecl,
+  ProjectMRsScope,
+  ProjectMRsData,
+  DiscussionsData,
+  MrByBranchEntry,
+  MrByBranchData,
+  Commands,
+  CommandName,
+} from "./commands.ts";
+
+export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
+export type { RelayEventType } from "./relay.ts";
+
+export { repoNameForPath } from "./repos.ts";

package/src/relay.ts

@@ -0,0 +1,61 @@
+/**
+ * Push events from the rt daemon's WebSocket relay (127.0.0.1:9401),
+ * `{ type, data, timestamp }` frames.
+ *
+ * Ported verbatim from mr-board's src/rt-client.ts.
+ */
+import type { RtClientOptions } from "./transport.ts";
+
+export type RelayEventType =
+  | "project-mrs"
+  | "discussions:update"
+  | "discussions:new-comments"
+  | "mr:status"
+  | (string & {});
+
+export const DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
+
+/**
+ * Subscribe to the daemon's broadcast channel. Reconnects with capped
+ * exponential backoff (1s to 30s) until the returned stop function runs;
+ * the daemon being down just means silence, never a crash.
+ */
+export function subscribe(
+  onEvent: (type: RelayEventType, data: unknown) => void,
+  opts: RtClientOptions = {},
+): () => void {
+  const url = opts.wsUrl ?? DEFAULT_WS_URL;
+  let ws: WebSocket | null = null;
+  let stopped = false;
+  let attempt = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const connect = () => {
+    if (stopped) return;
+    ws = new WebSocket(url);
+    ws.onopen = () => { attempt = 0; };
+    ws.onmessage = (ev) => {
+      try {
+        const frame = JSON.parse(String(ev.data)) as { type?: unknown; data?: unknown };
+        if (typeof frame.type === "string") onEvent(frame.type, frame.data);
+      } catch {
+        // Non-JSON frame; ignore.
+      }
+    };
+    ws.onclose = () => {
+      if (stopped) return;
+      const delay = Math.min(30_000, 1_000 * 2 ** attempt++);
+      timer = setTimeout(connect, delay);
+    };
+    ws.onerror = () => {
+      try { ws?.close(); } catch { /* already closed */ }
+    };
+  };
+
+  connect();
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+    try { ws?.close(); } catch { /* already closed */ }
+  };
+}

package/src/repos.ts

@@ -0,0 +1,34 @@
+/**
+ * Repo-name resolution against rt's global index (~/.rt/repos.json), a flat
+ * `{ "<repoName>": "<absolute path>" }` map. Lets a client resolve "what
+ * directory am I in" to "what does the daemon call this repo" without
+ * maintaining its own copy of the mapping.
+ */
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+function defaultReposJsonPath(): string {
+  return join(homedir(), ".rt", "repos.json");
+}
+
+/**
+ * Exact-match lookup: returns the repo name whose recorded path equals
+ * `repoPath`, or null if the file is missing, corrupt, or has no match.
+ * Never throws -- a resolution failure just means the caller falls back to
+ * whatever it had before (an unqualified path, a prompt, etc).
+ */
+export function repoNameForPath(repoPath: string, reposJsonPath?: string): string | null {
+  const path = reposJsonPath ?? defaultReposJsonPath();
+  try {
+    if (!existsSync(path)) return null;
+    const raw = readFileSync(path, "utf8");
+    const index = JSON.parse(raw) as Record<string, unknown>;
+    for (const [repoName, value] of Object.entries(index)) {
+      if (value === repoPath) return repoName;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/transport.ts

@@ -0,0 +1,46 @@
+/**
+ * rt daemon transport: HTTP over a unix socket (`~/.rt/rt.sock`).
+ *
+ * POST http://localhost/<cmd> with a JSON payload, response envelope
+ * `{ ok, data?, error? }`. Every call degrades to `{ ok: false, error }`
+ * instead of throwing, so callers surface daemon-down verbatim.
+ *
+ * Ported verbatim from mr-board's src/rt-client.ts.
+ */
+import { homedir } from "os";
+import { join } from "path";
+
+export interface RtResponse<T = unknown> {
+  ok: boolean;
+  data?: T;
+  error?: string;
+}
+
+export interface RtClientOptions {
+  sockPath?: string;
+  wsUrl?: string;
+}
+
+export const DEFAULT_SOCK = join(homedir(), ".rt", "rt.sock");
+
+export async function rtCommand<T = unknown>(
+  cmd: string,
+  payload: Record<string, unknown>,
+  opts: { sockPath?: string; timeoutMs?: number } = {},
+): Promise<RtResponse<T>> {
+  const sockPath = opts.sockPath ?? DEFAULT_SOCK;
+  try {
+    const res = await fetch(`http://localhost/${cmd}`, {
+      unix: sockPath,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+      // Bun's `unix` fetch option isn't in the standard RequestInit type.
+    } as RequestInit);
+    return (await res.json()) as RtResponse<T>;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `rt daemon unreachable at ${sockPath}: ${msg}` };
+  }
+}