@beast01/tcurl 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,114 @@
+# tcurl
+
+An interactive terminal UI (TUI) for building, sending, and saving HTTP
+requests — **curl, but comfortable.** Create requests of any method
+(`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`), tweak headers,
+query params, body and auth, fire them off, and browse the response — all
+without leaving your terminal. Requests are saved to disk so you can reuse
+them later.
+
+Styled with the **Gruvbox** and **Ember** color themes. Works on macOS,
+Linux, and Windows (any terminal with a TTY). Zero native dependencies.
+
+```
+┌ tcurl — interactive HTTP client ──────────────── gruvbox ┐
+│ ┌ Saved requests (2) ──┐ ┌ GET  Get users ──────────────┐ │
+│ │ ❯ GET    Get users   │ │ GET https://api.site/users   │ │
+│ │   POST   Create user │ │ Auth       bearer            │ │
+│ └──────────────────────┘ │ Headers    2                 │ │
+│                          └──────────────────────────────┘ │
+│  n new   ↵ edit   s send   d delete   y curl   ? help     │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+npm install -g tcurl
+```
+
+Requires **Node.js ≥ 18**.
+
+## Usage
+
+```bash
+tcurl                          # launch the interactive TUI
+tcurl https://api.example.com  # launch with a new request prefilled
+tcurl -X POST https://api.example.com/items
+tcurl --theme ember            # start with the Ember theme
+tcurl --help
+```
+
+### Keyboard
+
+**List view**
+
+| Key          | Action                          |
+| ------------ | ------------------------------- |
+| `↑` / `↓`    | Move selection                  |
+| `n`          | New request                     |
+| `Enter` / `e`| Edit request                    |
+| `s`          | Send request                    |
+| `d`          | Delete request                  |
+| `y`          | Copy as `curl` (prints on exit) |
+| `t`          | Cycle theme (gruvbox / ember)   |
+| `?`          | Help                            |
+| `q` / `Ctrl+C` | Quit                          |
+
+**Editor**
+
+| Key                | Action                                       |
+| ------------------ | -------------------------------------------- |
+| `↑` / `↓` / `Tab`  | Move between fields                          |
+| `←` / `→` / `Space`| Change method, body type, toggles            |
+| `Enter`            | Edit the focused field                       |
+| `Ctrl+S`           | Save a multi-line field (body, headers…)     |
+| `Esc`              | Back to list (auto-saves)                    |
+
+**Response**
+
+| Key             | Action              |
+| --------------- | ------------------- |
+| `↑`/`↓`/`j`/`k` | Scroll              |
+| `PgUp`/`PgDn`   | Page scroll         |
+| `g` / `G`       | Jump to top/bottom  |
+| `Tab` / `h`     | Body ↔ Headers      |
+| `Esc`           | Back                |
+
+## Features
+
+- **All HTTP methods** — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
+- **Body modes** — none, raw text, JSON (auto content-type), and
+  URL-encoded form (`key=value` per line).
+- **Headers & query params** — edited as simple `Key: Value` / `key=value`
+  lines.
+- **Auth** — Bearer token or HTTP Basic (username / password).
+- **Redirects** — follow (with method downgrade on 301/302/303) or manual.
+- **TLS control** — toggle certificate verification for self-signed hosts.
+- **Timeouts** — per-request, in milliseconds.
+- **Pretty responses** — JSON is auto-formatted; scrollable body & headers
+  with status, timing, and size.
+- **Persistence** — requests are stored as JSON and reused across sessions.
+- **Export** — copy any saved request as an equivalent `curl` command.
+
+## Where is my data?
+
+Saved requests and your theme choice live in a single JSON file under your
+platform's config directory (via [`env-paths`](https://www.npmjs.com/package/env-paths)):
+
+- Linux: `~/.config/tcurl/store.json`
+- macOS: `~/Library/Preferences/tcurl/store.json`
+- Windows: `%APPDATA%\tcurl\Config\store.json`
+
+## Development
+
+```bash
+npm install
+npm run build      # compile TypeScript to dist/
+npm run dev        # watch-compile
+node dist/cli.js   # run locally
+```
+
+## License
+
+MIT

package/dist/app.js

@@ -0,0 +1,170 @@
+import React, { useEffect, useState } from 'react';
+import { Box, Text, useApp, useInput, useStdout } from 'ink';
+import { getTheme, themes } from './theme.js';
+import { defaultRequest, saveStore } from './storage.js';
+import { executeRequest } from './http/client.js';
+import { toCurl } from './lib/curlgen.js';
+import { Header } from './components/Header.js';
+import { StatusBar } from './components/StatusBar.js';
+import { RequestList } from './components/RequestList.js';
+import { RequestEditor } from './components/RequestEditor.js';
+import { ResponseViewer } from './components/ResponseViewer.js';
+import { Help } from './components/Help.js';
+import { Spinner } from './components/Spinner.js';
+function useDimensions() {
+    const { stdout } = useStdout();
+    const [dims, setDims] = useState({
+        cols: stdout?.columns ?? 80,
+        rows: stdout?.rows ?? 24,
+    });
+    useEffect(() => {
+        if (!stdout)
+            return;
+        const onResize = () => setDims({ cols: stdout.columns, rows: stdout.rows });
+        stdout.on('resize', onResize);
+        return () => {
+            stdout.off('resize', onResize);
+        };
+    }, [stdout]);
+    return dims;
+}
+export function App({ initialStore, exitState, }) {
+    const { exit } = useApp();
+    const { cols, rows } = useDimensions();
+    const [store, setStore] = useState(initialStore);
+    const [selected, setSelected] = useState(0);
+    const [mode, setMode] = useState('list');
+    const [working, setWorking] = useState(null);
+    const [response, setResponse] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [flash, setFlash] = useState(null);
+    const theme = getTheme(store.theme);
+    const requests = store.requests;
+    function persist(next) {
+        setStore(next);
+        saveStore(next).catch(() => {
+            /* non-fatal: keep running even if disk write fails */
+        });
+    }
+    function flashMessage(msg) {
+        setFlash(msg);
+        setTimeout(() => setFlash(null), 2500);
+    }
+    function upsertWorking(r) {
+        const idx = requests.findIndex((x) => x.id === r.id);
+        const nextRequests = idx === -1 ? [...requests, r] : requests.map((x) => (x.id === r.id ? r : x));
+        persist({ ...store, requests: nextRequests });
+    }
+    async function send(config) {
+        if (!config.url.trim()) {
+            flashMessage('Set a URL first');
+            return;
+        }
+        setLoading(true);
+        setResponse(null);
+        const result = await executeRequest(config);
+        setResponse(result);
+        setLoading(false);
+        setMode('response');
+    }
+    // Global keys — only in list mode and when idle.
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c') {
+            exit();
+            return;
+        }
+        if (loading)
+            return;
+        if (input === '?') {
+            setMode('help');
+            return;
+        }
+        if (input === 'q') {
+            exit();
+            return;
+        }
+        if (input === 't') {
+            const names = Object.keys(themes);
+            const next = names[(names.indexOf(store.theme) + 1) % names.length];
+            persist({ ...store, theme: next });
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            setSelected((s) => Math.max(0, s - 1));
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            setSelected((s) => Math.min(requests.length - 1, s + 1));
+            return;
+        }
+        if (input === 'n') {
+            const r = defaultRequest();
+            setWorking(r);
+            setMode('editor');
+            return;
+        }
+        if ((key.return || input === 'e') && requests[selected]) {
+            setWorking({ ...requests[selected] });
+            setMode('editor');
+            return;
+        }
+        if (input === 's' && requests[selected]) {
+            send(requests[selected]);
+            return;
+        }
+        if (input === 'd' && requests[selected]) {
+            const next = requests.filter((_, i) => i !== selected);
+            persist({ ...store, requests: next });
+            setSelected((s) => Math.max(0, Math.min(s, next.length - 1)));
+            flashMessage('Deleted');
+            return;
+        }
+        if (input === 'y' && requests[selected]) {
+            exitState.curl = toCurl(requests[selected]);
+            flashMessage('curl command will print on exit');
+            return;
+        }
+    }, { isActive: mode === 'list' && !loading });
+    // Editor callbacks
+    function onEditorChange(r) {
+        setWorking(r);
+    }
+    function onEditorBack() {
+        if (working) {
+            upsertWorking(working);
+            const idx = requests.findIndex((x) => x.id === working.id);
+            if (idx !== -1)
+                setSelected(idx);
+            else
+                setSelected(requests.length); // newly added goes last
+        }
+        setWorking(null);
+        setMode('list');
+    }
+    function onEditorSend() {
+        if (working) {
+            upsertWorking(working);
+            send(working);
+        }
+    }
+    const statusHints = mode === 'list'
+        ? [
+            { key: 'n', label: 'new' },
+            { key: '↵', label: 'edit' },
+            { key: 's', label: 'send' },
+            { key: 'd', label: 'delete' },
+            { key: 'y', label: 'curl' },
+            { key: 't', label: 'theme' },
+            { key: '?', label: 'help' },
+            { key: 'q', label: 'quit' },
+        ]
+        : [];
+    return (React.createElement(Box, { flexDirection: "column", width: cols, minHeight: rows - 1 },
+        React.createElement(Header, { theme: theme, subtitle: mode === 'list' ? `${requests.length} saved · ` : '' }),
+        React.createElement(Box, { flexGrow: 1, flexDirection: "column", marginTop: 1 }, loading ? (React.createElement(Box, { flexGrow: 1, borderStyle: "round", borderColor: theme.border, paddingX: 1, alignItems: "center", justifyContent: "center" },
+            React.createElement(Spinner, { theme: theme, label: "Sending request\u2026" }))) : mode === 'help' ? (React.createElement(Help, { theme: theme, onClose: () => setMode('list') })) : mode === 'editor' && working ? (React.createElement(RequestEditor, { theme: theme, request: working, isActive: mode === 'editor', onChange: onEditorChange, onSend: onEditorSend, onBack: onEditorBack })) : mode === 'response' && response ? (React.createElement(ResponseViewer, { theme: theme, response: response, isActive: mode === 'response', onBack: () => setMode('list'), width: cols, height: rows })) : (React.createElement(RequestList, { theme: theme, requests: requests, selectedIndex: selected }))),
+        React.createElement(Box, { justifyContent: "space-between" },
+            React.createElement(StatusBar, { theme: theme, hints: statusHints }),
+            flash ? (React.createElement(Box, { paddingX: 1 },
+                React.createElement(Text, { color: theme.info }, flash))) : null)));
+}

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { App } from './app.js';
+import { loadStore, saveStore, storeLocation } from './storage.js';
+const VERSION = '1.0.0';
+const HELP = `
+tcurl — an interactive terminal UI for HTTP requests.
+
+Usage:
+  tcurl                 Launch the interactive TUI
+  tcurl [url]           Launch and prefill a new request with [url]
+
+Options:
+  -X, --method <m>      Prefill method (used with a url)
+  --theme <name>        Start with a theme (gruvbox | ember)
+  -h, --help            Show this help
+  -v, --version         Show version
+
+Inside the TUI, press ? for the full keyboard reference.
+Saved requests live at:
+  ${storeLocation()}
+`;
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-X' || a === '--method') {
+            out.method = (argv[++i] ?? '').toUpperCase();
+        }
+        else if (a === '--theme') {
+            out.theme = argv[++i];
+        }
+        else if (!a.startsWith('-')) {
+            out.url = a;
+        }
+    }
+    return out;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(HELP + '\n');
+        return;
+    }
+    if (argv.includes('-v') || argv.includes('--version')) {
+        process.stdout.write(`tcurl ${VERSION}\n`);
+        return;
+    }
+    if (!process.stdout.isTTY || !process.stdin.isTTY) {
+        process.stderr.write('tcurl requires an interactive terminal (TTY). Run it directly in your terminal.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const args = parseArgs(argv);
+    const store = await loadStore();
+    if (args.theme && (args.theme === 'gruvbox' || args.theme === 'ember')) {
+        store.theme = args.theme;
+    }
+    // Prefill a new request from CLI args and persist it so it appears in the list.
+    if (args.url) {
+        const { defaultRequest } = await import('./storage.js');
+        const r = defaultRequest({
+            url: args.url,
+            name: args.url,
+            method: args.method || 'GET',
+        });
+        store.requests.push(r);
+        await saveStore(store);
+    }
+    const exitState = { curl: null };
+    const { waitUntilExit } = render(React.createElement(App, { initialStore: store, exitState: exitState }), { exitOnCtrlC: false });
+    await waitUntilExit();
+    if (exitState.curl) {
+        process.stdout.write('\n' + exitState.curl + '\n');
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`tcurl: ${err?.stack ?? err}\n`);
+    process.exitCode = 1;
+});

package/dist/components/Header.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+export function Header({ theme, subtitle }) {
+    return (React.createElement(Box, { borderStyle: "round", borderColor: theme.border, paddingX: 1, justifyContent: "space-between" },
+        React.createElement(Text, null,
+            React.createElement(Text, { color: theme.accent, bold: true }, ' tcurl '),
+            React.createElement(Text, { color: theme.fgDim }, "\u2014 interactive HTTP client")),
+        React.createElement(Text, { color: theme.muted },
+            subtitle ?? '',
+            React.createElement(Text, { color: theme.info },
+                " ",
+                theme.name))));
+}

package/dist/components/Help.js

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+const SECTIONS = [
+    {
+        title: 'List view',
+        rows: [
+            ['↑ / ↓', 'Move selection'],
+            ['n', 'New request'],
+            ['Enter / e', 'Edit request'],
+            ['s', 'Send request'],
+            ['d', 'Delete request'],
+            ['y', 'Copy as curl (prints on exit)'],
+            ['t', 'Cycle theme (gruvbox / ember)'],
+            ['? ', 'Toggle this help'],
+            ['q / Ctrl+C', 'Quit'],
+        ],
+    },
+    {
+        title: 'Editor',
+        rows: [
+            ['↑ / ↓ / Tab', 'Move between fields'],
+            ['← / → / Space', 'Change method, body type, toggles'],
+            ['Enter', 'Edit the focused field'],
+            ['Ctrl+S', 'Save multi-line field'],
+            ['Esc', 'Back to list (auto-saves)'],
+        ],
+    },
+    {
+        title: 'Response',
+        rows: [
+            ['↑ / ↓ / j / k', 'Scroll'],
+            ['PgUp / PgDn', 'Page scroll'],
+            ['g / G', 'Top / bottom'],
+            ['Tab / h', 'Switch body / headers'],
+            ['Esc', 'Back'],
+        ],
+    },
+];
+export function Help({ theme, onClose }) {
+    useInput((input, key) => {
+        if (key.escape || input === '?' || input === 'q')
+            onClose();
+    });
+    return (React.createElement(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.borderActive, paddingX: 2, paddingY: 1, flexGrow: 1 },
+        React.createElement(Text, { color: theme.accent, bold: true }, "tcurl \u2014 keyboard reference"),
+        React.createElement(Box, { height: 1 }),
+        SECTIONS.map((section) => (React.createElement(Box, { key: section.title, flexDirection: "column", marginBottom: 1 },
+            React.createElement(Text, { color: theme.accentAlt, bold: true }, section.title),
+            section.rows.map(([k, desc]) => (React.createElement(Text, { key: k },
+                React.createElement(Text, { color: theme.accent }, k.padEnd(16)),
+                React.createElement(Text, { color: theme.fgDim }, desc))))))),
+        React.createElement(Text, { color: theme.muted }, "Press ? or Esc to close.")));
+}