waterplane 0.0.1 → 0.1.6

package/packages/host/dist/thumbs.js

@@ -0,0 +1,359 @@
+/**
+ * Server-side thumbnails — the single biggest bandwidth item on a bad link.
+ *
+ * The gallery grid, the new-image strip and the backlog attachment row all
+ * render `<img src=…/artifact?path=…>`, i.e. the ORIGINAL file. Measured on
+ * this machine's outbox dirs: 1170 images, 607 KB average, 14 MB worst case —
+ * so one scroll through a 300-row grid is well over 100 MB of a phone's
+ * tethered/roaming data. A 320 px JPEG of the same screenshot is ~15-30 KB.
+ *
+ * No image library is added for this: node has no decoder and `sharp` is a
+ * native dep that would have to build on every host. Instead we shell out to
+ * whatever the platform already ships — `sips` on macOS (part of the OS),
+ * ImageMagick or ffmpeg elsewhere — exactly like `host.ts` does for screen
+ * capture. If none is available, `thumbnail()` returns null and the caller
+ * serves the original, so the feature degrades to today's behaviour.
+ *
+ * Results are cached in `<STATE_DIR>/thumbs/` keyed by path+mtime+size+width,
+ * so a regenerated file at the same path gets a fresh thumb and the cache never
+ * serves a stale one. The dir is pruned to CACHE_MAX_BYTES (oldest first).
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { delimiter, extname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { BRAND } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+import { env } from "./env.js";
+import { writeTextAtomic } from "./jsonstore.js";
+const ENABLED = env("THUMBS") !== "0";
+/** Widths the client may ask for. An open list would let a caller fill the cache. */
+const WIDTHS = [160, 240, 320, 480, 640, 960, 1280, 1600];
+/** Below this the original is already thumbnail-sized — re-encoding costs more than it saves. */
+const MIN_SOURCE_BYTES = 48 * 1024;
+const CACHE_MAX_BYTES = 256 * 1024 * 1024;
+/** Guard against a pathological source (a 200 MP PNG) wedging a converter. */
+const CONVERT_TIMEOUT_MS = 20_000;
+const THUMBABLE = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".heic", ".heif", ".tif", ".tiff"]);
+const VIDEO = new Set([".mp4", ".webm", ".mov", ".m4v", ".ogv", ".mkv"]);
+/**
+ * ImageMagick picks a decoder by file CONTENT, so a committed `foo.png` that is
+ * really MVG/MSL/TEXT (local file read into the thumb) or a `foo.mp4` that is an
+ * HLS/concat playlist (outbound fetch, local read) would be interpreted. Two
+ * belts: name the decoder from the extension (`png:<file>`, `-f mov`), and a
+ * policy that denies the scriptable coders outright.
+ */
+const DENIED_CODERS = ["MVG", "MSL", "TEXT", "SVG", "PS", "EPS", "PDF", "XPS", "URL", "HTTP", "HTTPS", "FTP", "LABEL", "CAPTION", "EPHEMERAL"];
+const POLICY_XML = `<policymap>\n${DENIED_CODERS.map((c) => `  <policy domain="coder" rights="none" pattern="${c}"/>`).join("\n")}\n  <policy domain="path" rights="none" pattern="@*"/>\n</policymap>\n`;
+const MAGICK_CODER = {
+    ".png": "png", ".jpg": "jpeg", ".jpeg": "jpeg", ".gif": "gif", ".webp": "webp", ".bmp": "bmp",
+    ".heic": "heic", ".heif": "heic", ".tif": "tiff", ".tiff": "tiff",
+};
+const FFMPEG_DEMUXER = {
+    ".mp4": "mov", ".mov": "mov", ".m4v": "mov", ".webm": "matroska", ".mkv": "matroska", ".ogv": "ogg",
+    ".heic": "image2", ".heif": "image2", ".png": "image2", ".jpg": "image2", ".jpeg": "image2", ".gif": "image2", ".webp": "image2",
+    ".bmp": "image2", ".tif": "image2", ".tiff": "image2",
+};
+let cacheDir = "";
+let policyDir = "";
+/** Set once at boot; until then thumbnails are off (no root = nowhere to cache). */
+export function initThumbs(root) {
+    const state = hostStateDir(root);
+    cacheDir = join(state, "thumbs");
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+    }
+    catch {
+        cacheDir = "";
+    }
+    try {
+        const dir = join(state, "thumbs-policy");
+        mkdirSync(dir, { recursive: true });
+        writeTextAtomic(join(dir, "policy.xml"), POLICY_XML);
+        policyDir = dir;
+    }
+    catch {
+        policyDir = "";
+    }
+}
+/** MAGICK_CONFIGURE_PATH with our deny policy first, keeping any path the user set. */
+function policyPath(dir) {
+    const prior = process.env.MAGICK_CONFIGURE_PATH;
+    return prior ? `${dir}${delimiter}${prior}` : dir;
+}
+/** The env that polices ImageMagick, or null before initThumbs wrote a policy. */
+export function magickEnv() {
+    return policyDir ? { MAGICK_CONFIGURE_PATH: policyPath(policyDir) } : null;
+}
+/** Snap a requested width to the allow-list, or null if it isn't one. */
+export function thumbWidth(raw) {
+    const n = Number(raw);
+    return Number.isFinite(n) && WIDTHS.includes(n) ? n : null;
+}
+export function canThumb(path) {
+    const ext = extname(path).toLowerCase();
+    return THUMBABLE.has(ext) || VIDEO.has(ext);
+}
+function run(cmd, args, env) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (ok) => { if (!done) {
+            done = true;
+            resolve(ok);
+        } };
+        try {
+            const p = spawn(cmd, args, { stdio: "ignore", ...(env ? { env: { ...process.env, ...env } } : {}) });
+            const timer = setTimeout(() => { try {
+                p.kill("SIGKILL");
+            }
+            catch { /* gone */ } finish(false); }, CONVERT_TIMEOUT_MS);
+            p.on("error", () => { clearTimeout(timer); finish(false); });
+            p.on("exit", (code) => { clearTimeout(timer); finish(code === 0); });
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+/** Which converters exist here — probed once, lazily. */
+let tools = null;
+async function probeTools() {
+    if (tools)
+        return tools;
+    const has = async (bin, ...args) => run(bin, args);
+    const magick = (await has("magick", "-version")) ? "magick"
+        : (await has("convert", "-version")) ? "convert" : null;
+    tools = {
+        sips: process.platform === "darwin" && (await has("sips", "--version")),
+        magick,
+        ffmpeg: await has("ffmpeg", "-version"),
+    };
+    return tools;
+}
+/**
+ * The command that encodes `src` down to `width` px wide as JPEG at `out`, or
+ * null when no tool here can do it safely. Pure: the decoder is always named
+ * from the EXTENSION, never left to content sniffing; an extension we have no
+ * decoder for gets no plan (the caller serves the original).
+ */
+export function convertPlan(src, out, width, tools) {
+    const ext = extname(src).toLowerCase();
+    const scale = `scale='min(${width},iw)':-2`;
+    const demuxer = FFMPEG_DEMUXER[ext];
+    if (VIDEO.has(ext)) {
+        if (!tools.ffmpeg || !demuxer)
+            return null;
+        // One frame a second in (past a black lead-in), scaled, never upscaled.
+        return { cmd: "ffmpeg", args: [
+                "-nostdin", "-y", "-loglevel", "error", "-ss", "1", "-protocol_whitelist", "file", "-f", demuxer, "-i", src,
+                "-frames:v", "1", "-vf", scale, "-q:v", "6", out,
+            ] };
+    }
+    if (tools.sips) {
+        // sips resamples in place-ish: --out writes the copy. -Z bounds the LONGEST
+        // edge, which is what we want for a grid cell either orientation.
+        return { cmd: "sips", args: ["-s", "format", "jpeg", "-s", "formatOptions", "60", "-Z", String(width), src, "--out", out] };
+    }
+    const coder = MAGICK_CODER[ext];
+    // No deny policy on disk ⇒ no magick: an unpoliced ImageMagick is the hole.
+    if (tools.magick && coder && tools.policyDir) {
+        // `Wx>` = shrink only. -auto-orient so an EXIF-rotated phone photo isn't sideways.
+        // Both `magick` and legacy `convert` take `<in> [ops] <out>`.
+        return {
+            cmd: tools.magick,
+            args: [`${coder}:${src}`, "-auto-orient", "-resize", `${width}x${width}>`, "-quality", "60", "-strip", out],
+            env: { MAGICK_CONFIGURE_PATH: policyPath(tools.policyDir) },
+        };
+    }
+    if (tools.ffmpeg && demuxer) {
+        return { cmd: "ffmpeg", args: [
+                "-nostdin", "-y", "-loglevel", "error", "-protocol_whitelist", "file", "-f", demuxer, ...(demuxer === "image2" ? ["-pattern_type", "none"] : []), "-i", src, "-vf", scale, "-q:v", "6", out,
+            ] };
+    }
+    return null;
+}
+async function convert(src, out, width) {
+    const t = await probeTools();
+    const plan = convertPlan(src, out, width, { ...t, policyDir: policyDir || undefined });
+    return plan ? run(plan.cmd, plan.args, plan.env) : false;
+}
+/** Trim the cache to CACHE_MAX_BYTES, oldest-used first. Best-effort. */
+function prune() {
+    if (!cacheDir)
+        return;
+    try {
+        const files = readdirSync(cacheDir).map((n) => {
+            try {
+                const st = statSync(join(cacheDir, n));
+                return { n, size: st.size, at: st.mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        }).filter((x) => !!x);
+        let total = files.reduce((s, f) => s + f.size, 0);
+        if (total <= CACHE_MAX_BYTES)
+            return;
+        files.sort((a, b) => a.at - b.at);
+        for (const f of files) {
+            if (total <= CACHE_MAX_BYTES * 0.8)
+                break;
+            try {
+                rmSync(join(cacheDir, f.n));
+                total -= f.size;
+            }
+            catch { /* raced */ }
+        }
+    }
+    catch { /* best-effort */ }
+}
+/** In-flight generations, so N parallel grid requests for one file run ONE convert. */
+const inflight = new Map();
+/**
+ * A JPEG thumbnail of `absPath` at `width`, or null when we can't/shouldn't make
+ * one (disabled, no converter, unsupported type, source already small enough,
+ * conversion failed). Null always means "serve the original".
+ */
+export async function thumbnail(absPath, width) {
+    if (!ENABLED || !cacheDir || !canThumb(absPath))
+        return null;
+    let st;
+    try {
+        st = statSync(absPath);
+    }
+    catch {
+        return null;
+    }
+    const isVideo = VIDEO.has(extname(absPath).toLowerCase());
+    // A small still is already its own thumbnail. A video never is — one frame of
+    // it is always smaller than the file, so size doesn't gate there.
+    if (!isVideo && st.size < MIN_SOURCE_BYTES)
+        return null;
+    const key = createHash("sha1").update(`${absPath}\0${st.mtimeMs}\0${st.size}\0${width}`).digest("hex");
+    const cached = join(cacheDir, `${key}.jpg`);
+    if (existsSync(cached)) {
+        try {
+            return { buf: readFileSync(cached), mime: "image/jpeg", key };
+        }
+        catch { /* fall through, regenerate */ }
+    }
+    let job = inflight.get(key);
+    if (!job) {
+        job = (async () => {
+            // Convert to a temp path and rename in, so a concurrent reader never sees
+            // a half-written JPEG at the cache path.
+            const tmp = join(tmpdir(), `${BRAND.slug}-thumb-${key}-${process.pid}.jpg`);
+            try {
+                const ok = await convert(absPath, tmp, width);
+                if (!ok || !existsSync(tmp))
+                    return null;
+                const buf = readFileSync(tmp);
+                // A "thumbnail" bigger than the source is a failed optimisation — drop it.
+                if (!isVideo && buf.length >= st.size)
+                    return null;
+                try {
+                    renameSync(tmp, cached);
+                    prune();
+                }
+                catch { /* cache write is optional */ }
+                return buf;
+            }
+            catch {
+                return null;
+            }
+            finally {
+                try {
+                    if (existsSync(tmp))
+                        rmSync(tmp);
+                }
+                catch { /* gone */ }
+            }
+        })().finally(() => inflight.delete(key));
+        inflight.set(key, job);
+    }
+    const buf = await job;
+    return buf ? { buf, mime: "image/jpeg", key } : null;
+}
+/** What this cache holds right now: files and bytes. Its own function because
+ *  the storage report must not readdir a directory whose layout is this
+ *  module's business — `.jpg` keyed by a hash is an implementation detail, and
+ *  a foreign walk of it would break the day it stops being one. */
+export function thumbCacheUsage() {
+    if (!cacheDir)
+        return null;
+    try {
+        let count = 0;
+        let bytes = 0;
+        for (const n of readdirSync(cacheDir)) {
+            try {
+                const st = statSync(join(cacheDir, n));
+                if (!st.isFile())
+                    continue;
+                count++;
+                bytes += st.size;
+            }
+            catch { /* raced with a prune */ }
+        }
+        return { count, bytes };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Throw away cached thumbnails written at or before `before` — the storage
+ * screen's clear.
+ *
+ * **The owner clears its own cache.** A foreign `rmSync` over this directory
+ * would race `thumbnail()`'s rename-in at a path an `inflight` promise is
+ * about to resolve from, and would have to know the naming scheme to avoid
+ * deleting a partial file it does not own.
+ *
+ * **`before` is the contract, not a name list.** A person was shown "1541
+ * files · 21 MB" measured at an instant, and the promise a clear makes is that
+ * nothing outside that reading goes. Sending 1541 filenames would keep the same
+ * promise with a 90 KB request body; an instant keeps it in one number — and
+ * unlike the transport sweep, the individual rows here were never the decision,
+ * because nobody chooses which thumbnails to keep.
+ *
+ * Files only, no recursion, symlinks skipped: the cache is flat by
+ * construction, so anything else in there is not this module's and is left
+ * alone.
+ */
+export function clearThumbCache(before) {
+    const out = { deleted: 0, bytes: 0, failed: 0 };
+    if (!cacheDir)
+        return out;
+    let names;
+    try {
+        names = readdirSync(cacheDir);
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        const full = join(cacheDir, n);
+        let st;
+        try {
+            st = lstatSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile())
+            continue; // a symlink or a directory is not ours
+        if (st.mtimeMs > before)
+            continue; // written since the reading — never on screen
+        try {
+            rmSync(full);
+            out.deleted++;
+            out.bytes += st.size;
+        }
+        catch {
+            out.failed++;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=thumbs.js.map

package/packages/host/dist/thumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbs.js","sourceRoot":"","sources":["../src/thumbs.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/tmuxreq.d.ts

@@ -0,0 +1,91 @@
+import type { Check } from "./doctor.js";
+import { onPath } from "./pathx.js";
+/**
+ * Is the retired `<PREFIX>TMUX` knob still set? It means nothing now — every
+ * session runs inside tmux — so any non-empty value is one `doctor` names as
+ * ignored, rather than letting someone believe `0` still turns tmux off.
+ */
+export declare function tmuxKnobSet(raw: string | undefined): boolean;
+/**
+ * The exact command that installs tmux on this machine, or null when there is no
+ * package manager we recognise. `has` answers "is this binary on PATH". Linux
+ * order: apt, dnf, pacman, zypper, apk — the same as the installer's
+ * `tmux_install_cmd`, so the two never name different commands.
+ */
+export declare function tmuxInstallCommand(platform: NodeJS.Platform, has: (bin: string) => boolean): string | null;
+/**
+ * Homebrew on PATH: its repository (`<repo>/bin/brew`, through any symlink) and
+ * whether this account may write to it. Homebrew belongs to the account that set
+ * it up; another account's `brew install` fails on permissions half-way through.
+ */
+export declare function brewHere(): {
+    repo: string;
+    writable: boolean;
+} | null;
+/** `tmuxInstallCommand`'s `has` on this machine: brew counts only when this account can install with it. */
+export declare function installHas(bin: string): boolean;
+/**
+ * The "how to install it" sentence, for a platform with or without a known command.
+ * `brewForeign`: Homebrew is here but belongs to another account (`brewHere`).
+ */
+export declare function tmuxInstallAdvice(platform: NodeJS.Platform, cmd: string | null, brewForeign?: boolean): string;
+/**
+ * Why a session is refused when tmux is required and missing — the sentence a
+ * phone shows for a create that spawned nothing. There is no way to run
+ * without tmux, so it names none.
+ */
+export declare function tmuxMissingSentence(platform: NodeJS.Platform, cmd: string | null, brewForeign?: boolean): string;
+/** `tmux -V` → the version as tmux prints it (`3.4`, `3.3a`, `next-3.5`), or null. */
+export declare function parseTmuxVersion(out: string | null | undefined): string | null;
+/**
+ * [major, minor] of a version string, or null when it is not a release number
+ * (`master`, an unparsable build). `next-3.5` is a pre-release OF 3.5, so it
+ * counts as 3.5.
+ */
+export declare function tmuxVersionNumber(v: string | null): [number, number] | null;
+/**
+ * The oldest tmux the generated `tmux.conf` (`sessions/tmux.ts`'s
+ * `ensureTmuxConf`) is written for: it sets `allow-passthrough`, an option tmux
+ * added in 3.3. An older server reports the unknown option as a config error,
+ * which tmux shows in the first pane — in view mode, where keystrokes are pager
+ * commands and a delivery types into nothing.
+ */
+export declare const TMUX_MIN: [number, number];
+/** The locale the host hands its tmux clients: `LC_ALL` beats `LC_CTYPE` beats `LANG`. */
+export declare function effectiveLocale(e: Record<string, string | undefined>): {
+    name: string;
+    value: string;
+} | null;
+export interface TmuxFacts {
+    /** The retired `<PREFIX>TMUX` knob's raw value, if the environment still sets it. */
+    knob?: string;
+    platform: NodeJS.Platform;
+    /** Where tmux is, or null when it is not on PATH. */
+    path: string | null;
+    /** `tmux -V`'s output, or null when it could not be run. */
+    versionOut: string | null;
+    /** `tmuxInstallCommand` for this machine. */
+    installCmd: string | null;
+    /** Homebrew is here but belongs to another account (`brewHere`). */
+    brewForeign?: boolean;
+    /** The host process's own environment (only the locale variables are read). */
+    env: Record<string, string | undefined>;
+}
+/**
+ * The preflight rows: `tmux-knob` (only when the retired knob is still set),
+ * `tmux` (present and its version) and
+ * `tmux-locale` (the trap `docs/notes/protocol-and-security.md` describes: a
+ * tmux client that cannot conclude its terminal is UTF-8 does not forward
+ * UTF-8, and prompt detection loses its `❯`). The clients are spawned `-u` and
+ * `ptyEnv()` supplies a UTF-8 `LANG` (`defaultLocale`) when the environment has NO locale, so
+ * the only case left that can be seen from here is a locale that is SET and is
+ * not UTF-8 — `ptyEnv` keeps that one, and the panes inherit it.
+ */
+export declare function tmuxChecks(f: TmuxFacts): Check[];
+export { onPath };
+/**
+ * Null when tmux can be spawned, else the sentence a session create is refused
+ * with. Asked per spawn, uncached: a PATH scan is microseconds, and someone who
+ * installs tmux after reading the sentence must not have to restart the host.
+ */
+export declare function tmuxRefusal(platform?: NodeJS.Platform): string | null;