jotview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Kevin Besinga
+
+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 @@
+# jotview
+
+Turn a markdown file into a [jotbins](https://jotbins.com) link that renders it.
+
+```bash
+npx jotview notes.md
+# https://jotbins.com/d#z:U1bwSM3JyecCAA
+```
+
+Zero dependencies. No install, no account, no config.
+
+## How it works
+
+The document is compressed and packed into the URL's **fragment** — the part
+after `#`. Fragments are never sent to a server, so for links 2000 characters
+or fewer nothing you write leaves your machine. Opening the link renders it
+entirely in the browser.
+
+## Usage
+
+```
+jotview <file>            mint a link from a file
+jotview                   read markdown from stdin
+
+  --raw                   never shorten; always the full /d URL
+  --short                 always shorten, even when small
+  --open                  open the link in your browser
+  --copy                  copy the link to your clipboard
+  --base-url <url>        override https://jotbins.com
+  -h, --help
+  -v, --version
+```
+
+Examples:
+
+```bash
+jotview README.md --open
+cat notes.md | jotview
+jotview notes.md | pbcopy
+LINK=$(jotview notes.md --raw)
+```
+
+## Shortening, and what it costs you
+
+A document's link grows with the document — roughly half the markdown's size in
+characters. A 20 KB file produces an ~8,700-character URL, which Discord, X, and
+most chat clients will not accept.
+
+So links over **2000 characters are shortened** via `surl.jotbins.com`, and
+jotview tells you on stderr when that happens:
+
+```
+note: uploaded to jotbins to shorten (8768 → 30 chars). use --raw to keep it local.
+```
+
+**Shortening uploads your document.** The fragment *is* the markdown, so storing
+the URL stores the text. Below the threshold nothing is uploaded and no network
+request is made at all. Use `--raw` to keep a long document local, accepting a
+URL too long to paste into most places.
+
+If the shortener is unreachable or rate-limited, jotview prints the full link
+and exits 0 — it never fails your pipeline over a shortening problem.
+
+## Output contract
+
+**stdout is the URL and nothing else.** Notices, warnings, and errors go to
+stderr, so `$(jotview x.md)` and `jotview x.md | pbcopy` stay clean.
+
+Exit codes: `0` success, `1` runtime error, `2` usage error.
+
+## Limits
+
+Input is capped at 1 MB, matching what the `/d` renderer will open.
+
+## Requirements
+
+Node 18 or newer.
+
+## License
+
+MIT

package/bin/jotview.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { run } from "../src/cli.js";
+
+const MIN_MAJOR = 18;
+const major = Number(process.versions.node.split(".")[0]);
+if (major < MIN_MAJOR) {
+  process.stderr.write(
+    `jotview requires Node ${MIN_MAJOR} or newer (found ${process.versions.node}).\n`,
+  );
+  process.exit(1);
+}
+
+const { version } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+// A downstream reader that exits early (`| head`, `| less` then `q`) closes
+// its end of the pipe. If the URL is still being flushed when that happens,
+// Node's default behavior is to throw on the stream's next write, crashing
+// the process after the URL was already delivered successfully. Treat EPIPE
+// as the benign "reader stopped listening" signal it is.
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") process.exit(0);
+  throw err;
+});
+
+process.exitCode = await run(process.argv.slice(2), {
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+  stdin: process.stdin,
+  isTTY: Boolean(process.stdin.isTTY),
+  version,
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "jotview",
+  "version": "0.1.0",
+  "description": "Turn a markdown file into a jotbins /d link. Zero dependencies.",
+  "type": "module",
+  "bin": { "jotview": "bin/jotview.js" },
+  "files": ["bin", "src", "vectors.json", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test" },
+  "keywords": ["markdown", "jotbins", "cli", "share"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/jotbins/jotview.git" },
+  "homepage": "https://github.com/jotbins/jotview#readme",
+  "bugs": { "url": "https://github.com/jotbins/jotview/issues" }
+}

package/src/cli.js

@@ -0,0 +1,214 @@
+import { readFileSync } from "node:fs";
+import { encode, JotviewError, MAX_DOC_BYTES } from "./codec.js";
+import {
+  shorten, shouldShorten, DEFAULT_BASE_URL, SHORTEN_THRESHOLD, SHORTENER_URL,
+} from "./shorten.js";
+import { openUrl, copyText } from "./platform.js";
+export { DEFAULT_BASE_URL };
+
+/** Host the failed-shorten disclosure points to — derived from SHORTENER_URL
+ *  so the two never drift apart. */
+const SHORTENER_HOST = new URL(SHORTENER_URL).host;
+
+export const HELP = `jotview — turn markdown into a jotbins /d link
+
+Usage:
+  jotview <file>            mint a link from a file
+  jotview                   read markdown from stdin
+
+Options:
+  --raw                     never shorten; always the full /d URL
+  --short                   always shorten, even when small
+  --open                    open the link in your browser
+  --copy                    copy the link to your clipboard
+  --base-url <url>          override ${DEFAULT_BASE_URL}
+  -h, --help                show this help
+  -v, --version             show the version
+
+Links 2000 characters or fewer are printed as-is and never leave your machine.
+Longer ones are shortened via surl.jotbins.com, which uploads the document.
+Use --raw to keep it local regardless of size.
+`;
+
+/**
+ * @typedef {object} Options
+ * @property {string|null} file
+ * @property {boolean} raw
+ * @property {boolean} short
+ * @property {boolean} open
+ * @property {boolean} copy
+ * @property {string} baseUrl
+ * @property {boolean} help
+ * @property {boolean} version
+ */
+
+/**
+ * @param {string[]} argv
+ * @returns {Options}
+ */
+export function parseArgs(argv) {
+  /** @type {Options} */
+  const opts = {
+    file: null, raw: false, short: false, open: false, copy: false,
+    baseUrl: DEFAULT_BASE_URL, help: false, version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--raw": opts.raw = true; break;
+      case "--short": opts.short = true; break;
+      case "--open": opts.open = true; break;
+      case "--copy": opts.copy = true; break;
+      case "-h": case "--help": opts.help = true; break;
+      case "-v": case "--version": opts.version = true; break;
+      case "--base-url": {
+        const value = argv[++i];
+        if (
+          value === undefined || value.startsWith("-") || !/^https?:\/\//.test(value)
+        ) {
+          throw new JotviewError(
+            "usage",
+            "--base-url needs an absolute http:// or https:// URL",
+          );
+        }
+        opts.baseUrl = value.replace(/\/+$/, "");
+        break;
+      }
+      default:
+        if (arg.startsWith("-")) throw new JotviewError("usage", `unknown flag: ${arg}`);
+        if (opts.file !== null) throw new JotviewError("usage", "pass at most one file");
+        opts.file = arg;
+    }
+  }
+  if (opts.raw && opts.short) {
+    throw new JotviewError("usage", "--raw and --short cannot be combined");
+  }
+  if (opts.short && opts.baseUrl !== DEFAULT_BASE_URL) {
+    throw new JotviewError("usage", `--short only works with ${DEFAULT_BASE_URL}`);
+  }
+  return opts;
+}
+
+/** @param {import("node:stream").Readable} stdin */
+async function readStdin(stdin) {
+  /** @type {Buffer[]} */
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of stdin) {
+    total += chunk.length;
+    // Check before buffering the chunk so a runaway pipe fails fast instead
+    // of accumulating unbounded memory on its way to the same rejection
+    // `encode()` would eventually throw anyway.
+    if (total > MAX_DOC_BYTES) {
+      throw new JotviewError(
+        "too-large",
+        `document is at least ${total} bytes; the limit is ${MAX_DOC_BYTES}`,
+      );
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * @param {Options} opts
+ * @param {{stdin: import("node:stream").Readable}} io
+ */
+async function readInput(opts, io) {
+  if (opts.file === null) return readStdin(io.stdin);
+  try {
+    return readFileSync(opts.file, "utf8");
+  } catch (err) {
+    const reason = /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+      ? "no such file"
+      : /** @type {Error} */ (err).message;
+    throw new JotviewError("read-failed", `cannot read ${opts.file}: ${reason}`);
+  }
+}
+
+/**
+ * Side effects that must never change the exit code — the URL is already on
+ * stdout, so a missing `xclip` is a warning, not a failure.
+ * @param {string} url
+ * @param {Options} opts
+ * @param {{stderr: (s: string) => void, spawnImpl?: Function}} io
+ */
+function applySideEffects(url, opts, io) {
+  if (opts.copy) {
+    const result = copyText(url, { spawnImpl: io.spawnImpl });
+    if (!result.ok) io.stderr(`note: could not copy (${result.reason}).\n`);
+  }
+  if (opts.open) {
+    const result = openUrl(url, { spawnImpl: io.spawnImpl });
+    if (!result.ok) io.stderr(`note: could not open a browser (${result.reason}).\n`);
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{stdout: (s: string) => void, stderr: (s: string) => void,
+ *          stdin: import("node:stream").Readable, isTTY: boolean,
+ *          version: string, spawnImpl?: Function}} io
+ *   `spawnImpl` is optional and test-only — it is threaded down to
+ *   `openUrl`/`copyText` so tests can assert on the command that would have
+ *   been spawned without touching a real browser or clipboard. `bin/jotview.js`
+ *   never sets it, so real usage is unaffected.
+ * @returns {Promise<number>} exit code
+ */
+export async function run(argv, io) {
+  /** @type {Options} */
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    io.stderr(`jotview: ${/** @type {Error} */ (err).message}\n\n${HELP}`);
+    return 2;
+  }
+
+  if (opts.help) { io.stdout(HELP); return 0; }
+  if (opts.version) { io.stdout(`${io.version}\n`); return 0; }
+
+  // Nothing piped in and no file named: block forever, or help. Help.
+  if (opts.file === null && io.isTTY) { io.stdout(HELP); return 0; }
+
+  try {
+    const md = await readInput(opts, io);
+    if (md.trim() === "") throw new JotviewError("empty", "input is empty");
+    const rawUrl = `${opts.baseUrl}/d#${encode(md)}`;
+
+    if (!shouldShorten(rawUrl, opts)) {
+      // Over the threshold, but the host isn't the shortenable default —
+      // don't nag about it on documents that were never going to need it.
+      if (opts.baseUrl !== DEFAULT_BASE_URL && rawUrl.length > SHORTEN_THRESHOLD) {
+        io.stderr(
+          `note: shortening skipped — only ${DEFAULT_BASE_URL} links can be ` +
+            "shortened. using the full link.\n",
+        );
+      }
+      io.stdout(`${rawUrl}\n`);
+      applySideEffects(rawUrl, opts, io);
+      return 0;
+    }
+
+    const result = await shorten(rawUrl);
+    let printed = rawUrl;
+    if (result.ok) {
+      printed = result.short;
+      io.stderr(
+        `note: uploaded to jotbins to shorten (${rawUrl.length} → ` +
+          `${printed.length} chars). use --raw to keep it local.\n`,
+      );
+    } else {
+      io.stderr(
+        `note: upload to the shortener failed (${result.reason}); using the full ` +
+          `link. the document may still have reached ${SHORTENER_HOST}.\n`,
+      );
+    }
+    io.stdout(`${printed}\n`);
+    applySideEffects(printed, opts, io);
+    return 0;
+  } catch (err) {
+    io.stderr(`jotview: ${/** @type {Error} */ (err).message}\n`);
+    return 1;
+  }
+}

package/src/codec.js

@@ -0,0 +1,42 @@
+import { deflateRawSync } from "node:zlib";
+
+/** Payload prefix. Versions the encoding; must match jotbins' fragmentDoc.ts. */
+export const PREFIX = "z:";
+
+/** Mirrors MAX_DOC_BYTES in jotbins' fragmentDoc.ts. Larger docs mint links
+ *  the browser refuses to open, so reject at encode time instead. */
+export const MAX_DOC_BYTES = 1_000_000;
+
+/** @typedef {"too-large" | "empty" | "not-found" | "usage" | "read-failed"} ErrorCode */
+
+export class JotviewError extends Error {
+  /** @param {ErrorCode} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = "JotviewError";
+    this.code = code;
+  }
+}
+
+/** @param {Buffer} buf */
+function toBase64Url(buf) {
+  return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+/**
+ * Encode markdown into a `z:` fragment payload.
+ * @param {string} md
+ * @returns {string}
+ */
+export function encode(md) {
+  const bytes = Buffer.from(md, "utf8");
+  if (bytes.length > MAX_DOC_BYTES) {
+    throw new JotviewError(
+      "too-large",
+      `document is ${bytes.length} bytes; the limit is ${MAX_DOC_BYTES}`,
+    );
+  }
+  // No `level` option: stay on zlib's default so output matches what browsers
+  // produce via CompressionStream("deflate-raw").
+  return PREFIX + toBase64Url(deflateRawSync(bytes));
+}

package/src/platform.js

@@ -0,0 +1,72 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {string} platform  a `process.platform` value
+ * @returns {{cmd: string, args: string[]}}
+ */
+export function openCommand(platform) {
+  switch (platform) {
+    case "darwin": return { cmd: "open", args: [] };
+    case "linux": return { cmd: "xdg-open", args: [] };
+    // The empty string is `start`'s title argument; without it a URL
+    // containing spaces or quotes is treated as the window title.
+    case "win32": return { cmd: "cmd", args: ["/c", "start", ""] };
+    default: throw new Error(`unsupported platform: ${platform}`);
+  }
+}
+
+/**
+ * @param {string} platform
+ * @returns {{cmd: string, args: string[]}}
+ */
+export function copyCommand(platform) {
+  switch (platform) {
+    case "darwin": return { cmd: "pbcopy", args: [] };
+    case "win32": return { cmd: "clip", args: [] };
+    case "linux": return { cmd: "xclip", args: ["-selection", "clipboard"] };
+    default: throw new Error(`unsupported platform: ${platform}`);
+  }
+}
+
+/**
+ * @param {{status: number|null, error?: Error}} result
+ * @param {string} cmd
+ * @returns {{ok: boolean, reason?: string}}
+ */
+function outcome(result, cmd) {
+  if (result.error) return { ok: false, reason: result.error.message };
+  if (result.status !== 0) return { ok: false, reason: `${cmd} exited with ${result.status}` };
+  return { ok: true };
+}
+
+/**
+ * @param {string} url
+ * @param {{platform?: string, spawnImpl?: typeof spawnSync}} [options]
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function openUrl(url, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const run = options.spawnImpl ?? spawnSync;
+  try {
+    const { cmd, args } = openCommand(platform);
+    return outcome(run(cmd, [...args, url]), cmd);
+  } catch (err) {
+    return { ok: false, reason: /** @type {Error} */ (err).message };
+  }
+}
+
+/**
+ * @param {string} text
+ * @param {{platform?: string, spawnImpl?: typeof spawnSync}} [options]
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function copyText(text, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const run = options.spawnImpl ?? spawnSync;
+  try {
+    const { cmd, args } = copyCommand(platform);
+    return outcome(run(cmd, args, { input: text }), cmd);
+  } catch (err) {
+    return { ok: false, reason: /** @type {Error} */ (err).message };
+  }
+}

package/src/shorten.js

@@ -0,0 +1,58 @@
+/** Canonical jotbins host. Lives here rather than in cli.js so the two modules
+ *  do not import each other: shortenability is this module's concern. */
+export const DEFAULT_BASE_URL = "https://jotbins.com";
+
+/** Where chat clients start refusing content — Discord's hard message cap.
+ *  Not a server-side limit: the fragment never reaches a server. */
+export const SHORTEN_THRESHOLD = 2000;
+
+export const SHORTENER_URL = "https://surl.jotbins.com/api/create";
+
+/** Milliseconds before giving up and emitting the raw URL instead. */
+const TIMEOUT_MS = 5000;
+
+/**
+ * @param {string} url
+ * @param {{raw: boolean, short: boolean, baseUrl: string}} opts
+ * @returns {boolean}
+ */
+export function shouldShorten(url, opts) {
+  if (opts.raw) return false;
+  // surl's allowlist accepts only jotbins.com hosts, so a custom base URL can
+  // never be shortened. Skip rather than fire a request guaranteed to 400.
+  if (opts.baseUrl !== DEFAULT_BASE_URL) return false;
+  if (opts.short) return true;
+  return url.length > SHORTEN_THRESHOLD;
+}
+
+/**
+ * Shorten a URL. Never throws — the caller falls back to the raw URL.
+ * @param {string} url
+ * @param {{endpoint?: string}} [options]
+ * @returns {Promise<{ok: true, short: string} | {ok: false, reason: string}>}
+ */
+export async function shorten(url, options = {}) {
+  const endpoint = options.endpoint ?? SHORTENER_URL;
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ url }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      return { ok: false, reason: `shortener returned ${response.status}` };
+    }
+    const data = await response.json();
+    // The value ends up on stdout and, with --open, as an argv element handed
+    // to `spawnSync("open", [value])`. Requiring an https:// scheme rules out
+    // a misbehaving or compromised shortener returning something like "-a" or
+    // a `javascript:` URL that a browser or shell would treat specially.
+    if (typeof data?.short_url !== "string" || !data.short_url.startsWith("https://")) {
+      return { ok: false, reason: "shortener returned an unexpected response" };
+    }
+    return { ok: true, short: data.short_url };
+  } catch (err) {
+    return { ok: false, reason: /** @type {Error} */ (err).message };
+  }
+}

package/vectors.json

@@ -0,0 +1,10 @@
+{
+  "note": "Shared with jotbins (src/lib/fragmentDoc.ts). Each entry pins a payload and the markdown it must decode to. Assert DECODE, not encode: DEFLATE is not canonical, so two conforming encoders may emit different valid byte streams for the same input.",
+  "vectors": [
+    { "name": "empty", "markdown": "", "payload": "z:AwA" },
+    { "name": "ascii", "markdown": "# Hello\n", "payload": "z:U1bwSM3JyecCAA" },
+    { "name": "unicode", "markdown": "# 日本語 — café 🎉\n", "payload": "z:ARsA5P8jIOaXpeacrOiqniDigJQgY2Fmw6kg8J-OiQo" },
+    { "name": "mermaid-fence", "markdown": "```mermaid\ngraph TD;\nA-->B;\n```\n", "payload": "z:S0hIyE0tyk3MTOFKL0osyFAIcbHmctTVtXOy5kpISOACAA" },
+    { "name": "multiline", "markdown": "# Title\n\nPara one.\n\n- a\n- b\n", "payload": "z:U1YIySzJSeXiCkgsSlTIz0vV4-LSVUjk0lVI4gIA" }
+  ]
+}