@profullstack/r3q 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc.
+
+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,81 @@
+# r3q
+
+A REST client for your terminal. Requests are files you can commit; the TUI is just a good way to look at them.
+
+```
+curl -fsSL https://bun.sh/install | bash   # if you need it
+bunx @profullstack/r3q ./examples
+```
+
+![three panes: collection, request, response](#)
+
+```
+ r3q  ~/api                                        3 requests  Tab panes  Enter send  r reload  q quit
+╭─ Collection ────────────────╮ ╭─ Request ────────────────────────────────────────────────────────────╮
+│ ERR     broken.http         │ │  POST    https://httpbin.org/post                                    │
+│ GET     httpbin-get.http    │ │                                                                      │
+│ POST    httpbin-post.http   │ │ Content-Type:                                       application/json │
+│                             │ │ Authorization:                                  Bearer sk-live-xxxxx │
+│                             │ │ ─ body ───────────────────────────────────────────────────────────── │
+│                             │ │ {"name": "r3q", "ok": true}                                          │
+│                             │ ╰──────────────────────────────────────────────────────────────────────╯
+│                             │ ╭─ Response ───────────────────────────────────── 200 OK  215ms  168B ─╮
+│                             │ │ {                                                                    │
+│                             │ │   "args": { "hello": "world" }                                       │
+╰─────────────────────────────╯ ╰──────────────────────────────────────────────────────────────────────╯
+ Enter Send  Tab Collection  ↑↓ Move  r Reload  q Quit
+```
+
+## Requests are files
+
+A request is a `.http` file, the format your editor already understands:
+
+```http
+# Comments before the request line are ignored.
+POST https://api.example.com/things
+Content-Type: application/json
+Authorization: Bearer {{TOKEN}}
+
+{"name": "thing"}
+```
+
+A blank line ends the headers and begins the body. That's the whole format.
+
+Because a request is a file, it diffs, reviews and merges like everything else in the repository. There is no binary workspace to export from, and no account to sign into.
+
+## Secrets stay out of the files
+
+`{{NAME}}` is filled from a `.env` beside the collection, falling back to the process environment. The file you commit holds the template; the value stays on your machine.
+
+```
+TOKEN=sk-live-xxxxx
+```
+
+`.env` is gitignored by default.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| `Enter` | Send the selected request |
+| `Tab` | Move between the collection and the response |
+| `↑` `↓` | Move the selection, or scroll the response body |
+| `PgUp` `PgDn` `Home` | Scroll the response body faster |
+| `r` | Reload the collection from disk |
+| `q` | Quit |
+
+## Status
+
+Early. It sends requests, resolves variables, and shows you the whole exchange. What it does not do yet:
+
+- **Syntax-highlighted JSON.** The response body is monochrome because styled text spans land in `@profullstack/hqtui` 0.3.0 — see [profullstack/hqtui#60](https://github.com/profullstack/hqtui/issues/60). This is the next thing to change.
+- Editing requests in the TUI. Edit the file; press `r`.
+- Collection runs, assertions, cookie jars, OpenAPI/Postman import.
+
+## Built with
+
+[hqtui](https://hqtui.com) — the terminal UI library. r3q exists partly to keep hqtui honest: a real application finds the gaps that a widget gallery does not.
+
+## Licence
+
+MIT

package/bin/r3q.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/main.js";

package/dist/collection.d.ts

@@ -0,0 +1,33 @@
+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;
+}
+/**
+ * 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 declare function parseRequest(source: string, id: string, path: string): RequestFile;
+/** Every `.http` file under `root`, depth first, in a stable order. */
+export declare function loadCollection(root: string): RequestFile[];
+/**
+ * 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 declare function interpolate(text: string, vars: Record<string, string>): string;
+export declare function resolveRequest(request: RequestFile, vars: Record<string, string>): RequestFile;

package/dist/collection.js

@@ -0,0 +1,125 @@
+/**
+ * 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";
+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, id, path) {
+    const fail = (error) => ({ 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].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 = {};
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        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) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        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, vars) {
+    return text.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (whole, name) => vars[name] ?? whole);
+}
+export function resolveRequest(request, vars) {
+    const headers = {};
+    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/dist/highlight.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { 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;
+}
+/**
+ * Split JSON into coloured tokens. Anything unparseable is emitted verbatim as
+ * `plain`, so malformed output stays readable rather than being swallowed.
+ */
+export declare function tokenizeJson(source: string): Token[];
+/** Highlighted JSON, one SpanLine per line, ready for ui.text(). */
+export declare function highlightJson(source: string, palette: JsonPalette): SpanLine[];
+/** Body text as span lines: highlighted when it is JSON, plain otherwise. */
+export declare function highlightBody(body: string, contentType: string, palette: JsonPalette): SpanLine[];
+export {};

package/dist/highlight.js

@@ -0,0 +1,104 @@
+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) {
+    const out = [];
+    let i = 0;
+    const push = (text, kind) => {
+        if (text !== "")
+            out.push({ text, kind });
+    };
+    while (i < source.length) {
+        const ch = source[i];
+        if (WHITESPACE.test(ch)) {
+            let j = i;
+            while (j < source.length && WHITESPACE.test(source[j]))
+                j++;
+            push(source.slice(i, j), "plain");
+            i = j;
+            continue;
+        }
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < source.length) {
+                const c = source[j];
+                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]))
+                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]))
+                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, palette) {
+    const lines = [];
+    let current = [];
+    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] });
+        });
+    }
+    lines.push(current);
+    return lines;
+}
+/** Body text as span lines: highlighted when it is JSON, plain otherwise. */
+export function highlightBody(body, contentType, palette) {
+    if (!/\bjson\b/i.test(contentType)) {
+        return body.split("\n").map((line) => (line === "" ? [] : [{ text: line, fg: palette.plain }]));
+    }
+    return highlightJson(body, palette);
+}

package/dist/main.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { type Container, type Theme } from "@profullstack/hqtui";
+import { type RequestFile } from "./collection.ts";
+import { type Exchange } from "./send.ts";
+import { type JsonPalette } from "./highlight.ts";
+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;
+}
+export declare function createState(root: string): State;
+/** JSON token colours, drawn from the active theme rather than hard-coded. */
+export declare function jsonPalette(theme: Theme): JsonPalette;
+export declare function view({ ui, theme, height }: {
+    ui: Container;
+    theme: Theme;
+    height: number;
+}, state: State): void;

package/dist/main.js

@@ -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 } from "@profullstack/hqtui";
+import { loadCollection, resolveRequest } from "./collection.js";
+import { formatBody, send, statusKind } from "./send.js";
+import { highlightBody } from "./highlight.js";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** Variables come from `.env` beside the collection, then the environment. */
+function loadVars(root) {
+    const vars = {};
+    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) {
+    return {
+        requests: loadCollection(root),
+        selected: 0,
+        offset: 0,
+        bodyOffset: 0,
+        sending: false,
+        pane: "collection",
+        vars: loadVars(root),
+        root,
+        note: "",
+    };
+}
+const methodColor = (theme, method) => ({
+    GET: theme.success, POST: theme.accent, PUT: theme.warning,
+    PATCH: theme.warning, DELETE: theme.danger,
+}[method] ?? theme.secondary);
+async function main() {
+    const root = resolve(process.argv[2] ?? ".");
+    const state = createState(root);
+    const app = await createApp({ theme: themes.dark, title: "r3q", quitKeys: ["ctrl+c"] });
+    const current = () => state.requests[state.selected];
+    const fire = async () => {
+        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) => {
+        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) {
+    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 }, state) {
+    {
+        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, 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);
+    });
+}