@profullstack/r3q 0.1.0

package/dist/send.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sending a request and describing what came back.
+ *
+ * The whole exchange is kept — status, headers, timing, body — because the
+ * point of a terminal REST client is inspecting the response, not just getting
+ * an exit code.
+ */
+import type { RequestFile } from "./collection.ts";
+export interface Exchange {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body: string;
+    /** Round trip in milliseconds. */
+    ms: number;
+    bytes: number;
+    contentType: string;
+    error?: string;
+}
+export declare function send(request: RequestFile, timeoutMs?: number): Promise<Exchange>;
+/** Pretty-print JSON, leaving anything else exactly as it arrived. */
+export declare function formatBody(body: string, contentType: string): string;
+/** The colour family for a status code, as a theme key. */
+export declare function statusKind(status: number): "success" | "accent" | "warning" | "danger" | "muted";

package/dist/send.js

@@ -0,0 +1,62 @@
+export async function send(request, timeoutMs = 30_000) {
+    const started = performance.now();
+    const empty = (error) => ({
+        status: 0, statusText: "", headers: [], body: "",
+        ms: performance.now() - started, bytes: 0, contentType: "", error,
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(request.url, {
+            method: request.method,
+            headers: request.headers,
+            body: request.body,
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        const body = await response.text();
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            headers: [...response.headers.entries()].sort((a, b) => a[0].localeCompare(b[0])),
+            body,
+            ms: performance.now() - started,
+            bytes: new TextEncoder().encode(body).length,
+            contentType: response.headers.get("content-type") ?? "",
+        };
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            return empty(`timed out after ${timeoutMs}ms`);
+        return empty(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Pretty-print JSON, leaving anything else exactly as it arrived. */
+export function formatBody(body, contentType) {
+    if (!/\bjson\b/i.test(contentType))
+        return body;
+    try {
+        return JSON.stringify(JSON.parse(body), null, 2);
+    }
+    catch {
+        // A content-type that lies is common enough not to be an error.
+        return body;
+    }
+}
+/** The colour family for a status code, as a theme key. */
+export function statusKind(status) {
+    if (status === 0)
+        return "danger";
+    if (status < 200)
+        return "muted";
+    if (status < 300)
+        return "success";
+    if (status < 400)
+        return "accent";
+    if (status < 500)
+        return "warning";
+    return "danger";
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@profullstack/r3q",
+  "version": "0.1.0",
+  "description": "A REST client for your terminal. Requests are files you can commit; the TUI is just a good way to look at them.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/profullstack/r3q",
+  "bin": {
+    "r3q": "./bin/r3q.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1",
+    "node": ">=22.6"
+  },
+  "scripts": {
+    "start": "bun src/main.ts",
+    "build": "bun x tsc -p tsconfig.json",
+    "typecheck": "bun x tsc -p tsconfig.json --noEmit",
+    "test": "bun test test",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@profullstack/hqtui": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26",
+    "typescript": "^7.0.2"
+  },
+  "keywords": [
+    "rest",
+    "http",
+    "client",
+    "tui",
+    "terminal",
+    "hqtui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/r3q.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/collection.ts

@@ -0,0 +1,135 @@
+/**
+ * A collection is a directory of request files. Nothing is hidden in a binary
+ * workspace: a request is a file, so it diffs, reviews and merges like the rest
+ * of the repository it lives in.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+export interface RequestFile {
+  /** Path relative to the collection root, used as the display name and id. */
+  id: string;
+  path: string;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+  /** Parse errors are carried rather than thrown: one bad file is not a crash. */
+  error?: string;
+}
+
+const METHODS = new Set([
+  "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE",
+]);
+
+/**
+ * The `.http` format, as understood by every editor that speaks it:
+ *
+ *   POST https://api.example.com/things
+ *   Content-Type: application/json
+ *
+ *   {"name": "thing"}
+ *
+ * A blank line ends the headers and starts the body. `#` and `//` are comments
+ * before the request line, so a file can explain itself.
+ */
+export function parseRequest(source: string, id: string, path: string): RequestFile {
+  const fail = (error: string): RequestFile =>
+    ({ id, path, method: "GET", url: "", headers: {}, error });
+
+  const lines = source.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = (lines[i] ?? "").trim();
+    if (line !== "" && !line.startsWith("#") && !line.startsWith("//")) break;
+    i++;
+  }
+  if (i >= lines.length) return fail("no request line");
+
+  const [method, ...rest] = (lines[i] as string).trim().split(/\s+/);
+  if (!method || !METHODS.has(method.toUpperCase())) {
+    return fail(`unknown method ${JSON.stringify(method ?? "")}`);
+  }
+  const url = rest.join(" ").trim();
+  if (url === "") return fail("no URL");
+  i++;
+
+  const headers: Record<string, string> = {};
+  for (; i < lines.length; i++) {
+    const line = lines[i] as string;
+    if (line.trim() === "") { i++; break; }
+    const colon = line.indexOf(":");
+    if (colon <= 0) return fail(`malformed header: ${line.trim()}`);
+    headers[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+  }
+
+  const body = lines.slice(i).join("\n").trim();
+  return {
+    id, path,
+    method: method.toUpperCase(),
+    url,
+    headers,
+    body: body === "" ? undefined : body,
+  };
+}
+
+/** Every `.http` file under `root`, depth first, in a stable order. */
+export function loadCollection(root: string): RequestFile[] {
+  const out: RequestFile[] = [];
+  const walk = (dir: string): void => {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir).sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.startsWith(".") || entry === "node_modules") continue;
+      const full = join(dir, entry);
+      let stats;
+      try {
+        stats = statSync(full);
+      } catch {
+        continue;
+      }
+      if (stats.isDirectory()) {
+        walk(full);
+      } else if (entry.endsWith(".http")) {
+        const id = relative(root, full).split(sep).join("/");
+        try {
+          out.push(parseRequest(readFileSync(full, "utf8"), id, full));
+        } catch (error) {
+          out.push({
+            id, path: full, method: "GET", url: "", headers: {},
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Substitute `{{name}}` from the environment.
+ *
+ * Values come from a `.env`-shaped file or the process environment, so secrets
+ * stay out of the committed request files.
+ */
+export function interpolate(text: string, vars: Record<string, string>): string {
+  return text.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (whole, name: string) => vars[name] ?? whole);
+}
+
+export function resolveRequest(request: RequestFile, vars: Record<string, string>): RequestFile {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(request.headers)) {
+    headers[interpolate(key, vars)] = interpolate(value, vars);
+  }
+  return {
+    ...request,
+    url: interpolate(request.url, vars),
+    headers,
+    body: request.body === undefined ? undefined : interpolate(request.body, vars),
+  };
+}

package/src/highlight.ts

@@ -0,0 +1,132 @@
+/**
+ * JSON syntax highlighting, as spans.
+ *
+ * A tokeniser rather than a set of regexes over each line: a regex cannot tell
+ * a key from a string value, and it colours the inside of a string that happens
+ * to contain a brace. Both look fine on the example you tested and wrong on
+ * real API output.
+ */
+import type { Span, SpanLine } from "@profullstack/hqtui";
+
+export interface JsonPalette {
+  key: number;
+  string: number;
+  number: number;
+  boolean: number;
+  null: number;
+  punctuation: number;
+  plain: number;
+}
+
+type Kind = keyof JsonPalette;
+
+export interface Token {
+  text: string;
+  kind: Kind;
+}
+
+const WHITESPACE = /\s/;
+
+/**
+ * Split JSON into coloured tokens. Anything unparseable is emitted verbatim as
+ * `plain`, so malformed output stays readable rather than being swallowed.
+ */
+export function tokenizeJson(source: string): Token[] {
+  const out: Token[] = [];
+  let i = 0;
+
+  const push = (text: string, kind: Kind): void => {
+    if (text !== "") out.push({ text, kind });
+  };
+
+  while (i < source.length) {
+    const ch = source[i] as string;
+
+    if (WHITESPACE.test(ch)) {
+      let j = i;
+      while (j < source.length && WHITESPACE.test(source[j] as string)) j++;
+      push(source.slice(i, j), "plain");
+      i = j;
+      continue;
+    }
+
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < source.length) {
+        const c = source[j] as string;
+        if (c === "\\") { j += 2; continue; }
+        if (c === '"') { j++; break; }
+        j++;
+      }
+      const text = source.slice(i, j);
+      // A string is a key when the next non-space character is a colon. This is
+      // the whole reason for tokenising rather than pattern matching.
+      let k = j;
+      while (k < source.length && WHITESPACE.test(source[k] as string)) k++;
+      push(text, source[k] === ":" ? "key" : "string");
+      i = j;
+      continue;
+    }
+
+    if (ch === "-" || (ch >= "0" && ch <= "9")) {
+      let j = i;
+      if (source[j] === "-") j++;
+      while (j < source.length && /[0-9.eE+\-]/.test(source[j] as string)) j++;
+      push(source.slice(i, j), "number");
+      i = j;
+      continue;
+    }
+
+    if (source.startsWith("true", i) || source.startsWith("false", i)) {
+      const word = source.startsWith("true", i) ? "true" : "false";
+      push(word, "boolean");
+      i += word.length;
+      continue;
+    }
+
+    if (source.startsWith("null", i)) {
+      push("null", "null");
+      i += 4;
+      continue;
+    }
+
+    if ("{}[],:".includes(ch)) {
+      push(ch, "punctuation");
+      i++;
+      continue;
+    }
+
+    // Something unexpected: emit one character and keep going rather than
+    // giving up on the rest of the document.
+    push(ch, "plain");
+    i++;
+  }
+  return out;
+}
+
+/** Highlighted JSON, one SpanLine per line, ready for ui.text(). */
+export function highlightJson(source: string, palette: JsonPalette): SpanLine[] {
+  const lines: SpanLine[] = [];
+  let current: SpanLine = [];
+  for (const token of tokenizeJson(source)) {
+    const parts = token.text.split("\n");
+    parts.forEach((part, index) => {
+      if (index > 0) { lines.push(current); current = []; }
+      if (part !== "") current.push({ text: part, fg: palette[token.kind] } satisfies Span);
+    });
+  }
+  lines.push(current);
+  return lines;
+}
+
+/** Body text as span lines: highlighted when it is JSON, plain otherwise. */
+export function highlightBody(
+  body: string,
+  contentType: string,
+  palette: JsonPalette,
+): SpanLine[] {
+  if (!/\bjson\b/i.test(contentType)) {
+    return body.split("\n").map((line) => (line === "" ? [] : [{ text: line, fg: palette.plain }]));
+  }
+  return highlightJson(body, palette);
+}

package/src/main.ts

@@ -0,0 +1,251 @@
+/**
+ * r3q — a REST client for your terminal.
+ *
+ *   bunx @profullstack/r3q            # the collection in the working directory
+ *   bunx @profullstack/r3q ./api      # a collection somewhere else
+ *
+ * Three panes: the collection, the request, the response. Enter sends.
+ */
+import { createApp, themes, type Container, type KeyEvent, type Theme } from "@profullstack/hqtui";
+import { loadCollection, resolveRequest, type RequestFile } from "./collection.ts";
+import { formatBody, send, statusKind, type Exchange } from "./send.ts";
+import { highlightBody, type JsonPalette } from "./highlight.ts";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface State {
+  requests: RequestFile[];
+  selected: number;
+  offset: number;
+  bodyOffset: number;
+  exchange?: Exchange;
+  sending: boolean;
+  pane: "collection" | "response";
+  vars: Record<string, string>;
+  root: string;
+  note: string;
+}
+
+/** Variables come from `.env` beside the collection, then the environment. */
+function loadVars(root: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  try {
+    for (const line of readFileSync(resolve(root, ".env"), "utf8").split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) continue;
+      vars[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+    }
+  } catch {
+    // No .env is the normal case, not a problem.
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && !(key in vars)) vars[key] = value;
+  }
+  return vars;
+}
+
+export function createState(root: string): State {
+  return {
+    requests: loadCollection(root),
+    selected: 0,
+    offset: 0,
+    bodyOffset: 0,
+    sending: false,
+    pane: "collection",
+    vars: loadVars(root),
+    root,
+    note: "",
+  };
+}
+
+const methodColor = (theme: Record<string, number>, method: string): number => ({
+  GET: theme.success, POST: theme.accent, PUT: theme.warning,
+  PATCH: theme.warning, DELETE: theme.danger,
+}[method] ?? theme.secondary) as number;
+
+async function main(): Promise<void> {
+  const root = resolve(process.argv[2] ?? ".");
+  const state = createState(root);
+
+  const app = await createApp({ theme: themes.dark, title: "r3q", quitKeys: ["ctrl+c"] });
+
+  const current = (): RequestFile | undefined => state.requests[state.selected];
+
+  const fire = async (): Promise<void> => {
+    const request = current();
+    if (!request || state.sending) return;
+    if (request.error) { state.note = request.error; app.invalidate(); return; }
+    state.sending = true;
+    state.note = "";
+    state.exchange = undefined;
+    state.bodyOffset = 0;
+    app.invalidate();
+    state.exchange = await send(resolveRequest(request, state.vars));
+    state.sending = false;
+    app.invalidate();
+  };
+
+  app.on("key", (event: KeyEvent) => {
+    switch (event.key) {
+      case "q": app.quit(); return;
+      case "tab": state.pane = state.pane === "collection" ? "response" : "collection"; return;
+      case "r": state.requests = loadCollection(state.root); state.note = "reloaded"; return;
+      case "enter": void fire(); return;
+      case "up":
+        if (state.pane === "collection") state.selected = Math.max(0, state.selected - 1);
+        else state.bodyOffset = Math.max(0, state.bodyOffset - 1);
+        return;
+      case "down":
+        if (state.pane === "collection") {
+          state.selected = Math.min(state.requests.length - 1, state.selected + 1);
+        } else state.bodyOffset += 1;
+        return;
+      case "pageup": state.bodyOffset = Math.max(0, state.bodyOffset - 20); return;
+      case "pagedown": state.bodyOffset += 20; return;
+      case "home": state.bodyOffset = 0; return;
+    }
+  });
+
+  app.render((args) => view(args, state));
+  await app.start();
+}
+
+
+/** JSON token colours, drawn from the active theme rather than hard-coded. */
+export function jsonPalette(theme: Theme): JsonPalette {
+  return {
+    key: theme.accent,
+    string: theme.success,
+    number: theme.warning,
+    boolean: theme.secondary,
+    null: theme.muted,
+    punctuation: theme.muted,
+    plain: theme.foreground,
+  };
+}
+
+export function view(
+  { ui, theme, height }: { ui: Container; theme: Theme; height: number },
+  state: State,
+): void {
+  {
+    ui.row({ size: 1 }, (header) => {
+      header.text(" r3q", { fg: theme.title, bold: true, size: 6 });
+      header.text(state.root, { fg: theme.muted });
+      header.text(
+        `${state.requests.length} requests  Tab panes  Enter send  r reload  q quit `,
+        { fg: theme.muted, align: "right" },
+      );
+    });
+
+    ui.row({ size: height - 2, gap: 1 }, (row) => {
+      row.panel({
+        title: "Collection",
+        width: "0.9fr",
+        borderColor: state.pane === "collection" ? theme.borderFocused : theme.border,
+      }, (p) => {
+        if (state.requests.length === 0) {
+          p.label(`No .http files under ${state.root}`);
+          p.label("Create one and press r to reload.");
+          return;
+        }
+        p.table({
+          rows: state.requests.map((r) => ({
+            method: r.error ? "ERR" : r.method,
+            name: r.id,
+          })),
+          selected: state.selected,
+          offset: state.offset,
+          followSelection: true,
+          scrollbar: true,
+          onScroll: (delta) => { state.offset = Math.max(0, state.offset + delta); },
+          onSelectRow: (index) => { state.selected = state.offset + index; },
+          header: false,
+          columns: [
+            { key: "method", title: "", width: 7, color: theme.secondary },
+            { key: "name", title: "", min: 10, color: theme.foreground },
+          ],
+        });
+      });
+
+      row.column({ width: "2fr", gap: 1 }, (right) => {
+        const request = state.requests[state.selected];
+        right.panel({ title: "Request", size: 9 }, (p) => {
+          if (!request) { p.label("Nothing selected."); return; }
+          if (request.error) {
+            p.text(`${request.id}: ${request.error}`, { fg: theme.danger, wrap: true });
+            return;
+          }
+          const resolved = resolveRequest(request, state.vars);
+          p.row({ size: 1 }, (r) => {
+            r.badge({ text: resolved.method, color: methodColor(theme as never, resolved.method), size: 8 });
+            r.text(` ${resolved.url}`, { fg: theme.foreground });
+          });
+          p.spacer(1);
+          const entries = Object.entries(resolved.headers);
+          if (entries.length > 0) {
+            p.keyValues(entries.map(([k, v]) => ({ label: `${k}:`, value: v, color: theme.muted })));
+          } else {
+            p.label("No headers.");
+          }
+          if (resolved.body) {
+            p.divider({ label: "body" });
+            p.text(resolved.body, { fg: theme.foreground, wrap: true });
+          }
+        });
+
+        const exchange = state.exchange;
+        const subtitle = state.sending
+          ? "sending…"
+          : exchange
+            ? `${exchange.status || "—"} ${exchange.statusText}  ${Math.round(exchange.ms)}ms  ${exchange.bytes}B`
+            : "press Enter";
+        right.panel({
+          title: "Response",
+          subtitle,
+          subtitleColor: exchange ? theme[statusKind(exchange.status)] : theme.muted,
+          size: "1fr",
+          borderColor: state.pane === "response" ? theme.borderFocused : theme.border,
+        }, (p) => {
+          if (state.note !== "") p.text(state.note, { fg: theme.warning, size: 1 });
+          if (state.sending) { p.label("Waiting for the server…"); return; }
+          if (!exchange) { p.label("No response yet."); return; }
+          if (exchange.error) { p.text(exchange.error, { fg: theme.danger, wrap: true }); return; }
+          p.keyValues(
+            exchange.headers.slice(0, 4).map(([k, v]) => ({ label: `${k}:`, value: v, color: theme.muted })),
+          );
+          p.divider({ label: "body" });
+          const body = highlightBody(
+            formatBody(exchange.body, exchange.contentType),
+            exchange.contentType,
+            jsonPalette(theme),
+          );
+          // One text() call per line rather than one for the whole body: the
+          // pane scrolls by line, so slicing here is what makes bodyOffset work.
+          for (const line of body.slice(state.bodyOffset, state.bodyOffset + 400)) {
+            p.text(line.length === 0 ? " " : line, { size: 1 });
+          }
+        });
+      });
+    });
+
+    ui.statusBar({
+      items: [
+        { key: "Enter", label: "Send" },
+        { key: "Tab", label: state.pane === "collection" ? "Collection" : "Response", active: true },
+        { key: "↑↓", label: "Move" },
+        { key: "r", label: "Reload" },
+        { key: "q", label: "Quit" },
+      ],
+    });
+  }
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}