handmux 0.23.0 → 0.24.0

package/dist/src/routes/files.js

@@ -0,0 +1,230 @@
+// File browsing under $HOME: read a doc, list/create a dir, download any file, and upload. The docs data
+// layer realpaths + enforces the under-$HOME containment; these routes only map {error,status} to HTTP
+// and own the multipart upload plumbing. Mounted under /api by createApiRouter.
+import express from 'express';
+import busboy from 'busboy';
+import { promises as fsp, createWriteStream } from 'node:fs';
+import { join as joinPath } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { safeUploadName } from '../docPath.js';
+import { isAllowedUploadExt } from '../uploadTypes.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+export function fileRoutes({ docs, uploadExts, maxUploadBytes }) {
+    const r = express.Router();
+    // Read a single text file under $HOME. The docs layer realpaths, enforces containment and rejects
+    // binary content; known Markdown/HTML extensions keep their richer renderer.
+    // the route only maps its {error,status} to an HTTP status.
+    r.get('/file', async (req, res, next) => {
+        try {
+            // Conditional read: `?mtime=<ms>` (the client's last-known mtime) lets the server answer
+            // `{ notModified: true }` without re-reading/re-sending an unchanged doc.
+            const m = Number(req.query.mtime);
+            const knownMtime = Number.isFinite(m) ? m : null;
+            const out = await docs.readDoc(typeof req.query.path === 'string' ? req.query.path : '', knownMtime);
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            if (out.notModified)
+                return res.json({ name: out.name, type: out.type, mtimeMs: out.mtimeMs, notModified: true });
+            return res.json({ name: out.name, type: out.type, content: out.content, mtimeMs: out.mtimeMs });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // List a directory under $HOME (empty path → $HOME). Only subdirs + md/html files are returned.
+    r.get('/dir', async (req, res, next) => {
+        try {
+            const out = await docs.listDir(typeof req.query.path === 'string' ? req.query.path : '');
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json(out);
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // Create a directory `name` inside `dir` (both must be under $HOME). docs.makeDir enforces the
+    // boundary check and validates the name; the route maps {error,status} to an HTTP response.
+    r.post('/dir', async (req, res, next) => {
+        const body = req.body;
+        const dir = isRecord(body) ? body.dir : undefined;
+        const name = isRecord(body) ? body.name : undefined;
+        if (typeof dir !== 'string' || typeof name !== 'string')
+            return res.status(400).json({ error: 'bad request' });
+        try {
+            const out = await docs.makeDir(dir, name);
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.status(201).json({ path: out.real });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // Download ANY regular file under $HOME (no extension white-list). docs.statForDownload enforces
+    // the realpath+isUnder boundary and the 50MB cap; res.download streams it and forces
+    // Content-Disposition: attachment (so HTML/SVG can never render inline → no stored-XSS via open).
+    r.get('/download', async (req, res, next) => {
+        try {
+            const out = await docs.statForDownload(typeof req.query.path === 'string' ? req.query.path : '');
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            // Conditional download for the inline image viewer: `?mtime=<ms>` (the client's last-known mtime)
+            // → 304 when unchanged, so a large image isn't re-streamed just to re-view it. `X-Mtime` on the
+            // 200 lets the client store the current mtime for the next check. Plain downloads pass no mtime.
+            const m = Number(req.query.mtime);
+            if (Number.isFinite(m) && m === out.mtimeMs)
+                return res.status(304).end();
+            res.setHeader('X-Mtime', String(out.mtimeMs));
+            return res.download(out.real, out.name, (err) => { if (err && !res.headersSent)
+                next(err); });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // First free filename in `dir`: the name as-is, else Finder-style "base (1).ext", "base (2).ext", …
+    // (the suffix goes before the extension). Bounded; a pathological fallback keeps it from looping.
+    async function freeUploadName(dir, name) {
+        const dot = name.lastIndexOf('.');
+        const base = dot > 0 ? name.slice(0, dot) : name;
+        const ext = dot > 0 ? name.slice(dot) : '';
+        let cand = name;
+        for (let n = 1; n <= 999; n++) {
+            try {
+                await fsp.access(joinPath(dir, cand));
+            } // exists → try the next suffix
+            catch {
+                return cand;
+            } // ENOENT → free
+            cand = `${base} (${n})${ext}`;
+        }
+        return `${base} (${randomBytes(3).toString('hex')})${ext}`;
+    }
+    // Upload a file into a directory under $HOME. Multipart streamed via busboy (the file never fully
+    // buffers in memory, and the size cap aborts mid-stream). Guards, in order: target dir must be a
+    // non-hidden subdir of home (resolveUploadDir); filename sanitised to a dotless basename; extension
+    // in the allow-list. A name clash auto-suffixes (never overwrites). The client appends `dir` BEFORE
+    // the file part, so the field is known by the time the file event fires.
+    r.post('/upload', (req, res) => {
+        let bb;
+        // defParamCharset:'utf8' — browsers put a non-ASCII (e.g. Chinese) filename into the multipart
+        // Content-Disposition as raw UTF-8 bytes; busboy's default 'latin1' would decode it to mojibake.
+        try {
+            bb = busboy({ headers: req.headers, defParamCharset: 'utf8', limits: { files: 1, fileSize: maxUploadBytes + 1 } });
+        }
+        catch {
+            return res.status(400).json({ error: 'bad multipart request' });
+        }
+        let dir = '';
+        let stash = false; // stash=1 → upload into the per-cwd space under ~/.handmux/uploads; `dir` is the cwd
+        let sawFile = false;
+        let handled = false;
+        let ws = null;
+        let tmp = null;
+        const done = (status, body) => {
+            if (!handled) {
+                handled = true;
+                res.status(status).json(body);
+            }
+        };
+        const cleanup = () => (tmp ? fsp.rm(tmp, { force: true }).catch(() => { }) : Promise.resolve());
+        bb.on('field', (name, val) => {
+            if (name === 'dir')
+                dir = val;
+            else if (name === 'stash')
+                stash = val === '1';
+        });
+        bb.on('file', async (_field, file, info) => {
+            sawFile = true;
+            try {
+                const name = safeUploadName(info.filename);
+                if (!name) {
+                    file.resume();
+                    return done(400, { error: 'bad filename' });
+                }
+                if (!isAllowedUploadExt(name, uploadExts)) {
+                    file.resume();
+                    return done(415, { error: 'type not allowed' });
+                }
+                const target = stash ? await docs.resolveStashDir(dir) : await docs.resolveUploadDir(dir);
+                if ('error' in target) {
+                    file.resume();
+                    return done(target.status, { error: target.error });
+                }
+                // Finder-style de-dup: never 409 / overwrite on a name clash — pick the first free "base (n).ext".
+                // Resolved up front for the response; re-resolved at link time if the race is lost (see below).
+                const origName = name;
+                let finalName = await freeUploadName(target.real, origName);
+                let dest = joinPath(target.real, finalName);
+                const tempPath = joinPath(target.real, `.${finalName}.uploading-${randomBytes(6).toString('hex')}`);
+                tmp = tempPath;
+                const writeStream = createWriteStream(tempPath);
+                ws = writeStream;
+                writeStream.on('error', () => { file.resume(); cleanup().finally(() => done(500, { error: 'write failed' })); });
+                writeStream.on('finish', async () => {
+                    // busboy sets file.truncated synchronously when it emits 'limit'; it's reliably true here
+                    // if the stream exceeded the cap. (We size the limit at cap+1 so a file of EXACTLY
+                    // maxUploadBytes is allowed; only strictly-larger trips it.)
+                    if (file.truncated) {
+                        await cleanup();
+                        return done(413, { error: 'too large' });
+                    }
+                    try {
+                        // link (NOT rename): if the name appeared meanwhile (a concurrent upload won the race) link
+                        // throws EEXIST → we pick the NEXT free suffix and retry, so we still never overwrite another
+                        // file, and a clash auto-suffixes rather than 409s.
+                        let linked = false;
+                        for (let attempt = 0; attempt < 6 && !linked; attempt++) {
+                            try {
+                                await fsp.link(tempPath, dest);
+                                linked = true;
+                            }
+                            catch (e) {
+                                if (errorCode(e) !== 'EEXIST')
+                                    throw e;
+                                finalName = await freeUploadName(target.real, origName);
+                                dest = joinPath(target.real, finalName);
+                            }
+                        }
+                        if (!linked) {
+                            await cleanup();
+                            return done(409, { error: 'exists' });
+                        }
+                        await cleanup(); // link made dest a second name for the data; drop the temp name
+                        const st = await fsp.stat(dest);
+                        done(201, { name: finalName, size: st.size, path: dest }); // absolute path: the dock pastes it in
+                    }
+                    catch {
+                        await cleanup();
+                        done(500, { error: 'finalize failed' });
+                    }
+                });
+                return void file.pipe(writeStream);
+            }
+            catch {
+                // resolveUploadDir / fs errors etc. — never let the async handler reject (busboy won't catch
+                // it → unhandledRejection + hung request).
+                file.resume();
+                await cleanup();
+                return done(500, { error: 'upload failed' });
+            }
+        });
+        bb.on('error', () => { cleanup().finally(() => done(400, { error: 'parse error' })); });
+        bb.on('close', () => { if (!sawFile)
+            done(400, { error: 'no file' }); });
+        // Client aborted mid-upload (mobile networks drop constantly). req.pipe(bb) does NOT forward the
+        // source's destroy to busboy, so ws/file/bb emit nothing — we'd leak the half-written temp file
+        // and its fd on every dropped upload. Clean up ourselves on abort.
+        req.on('aborted', () => { if (handled)
+            return; handled = true; if (ws)
+            ws.destroy(); cleanup(); });
+        return req.pipe(bb);
+    });
+    return r;
+}

package/dist/src/routes/git.js

@@ -0,0 +1,78 @@
+// git viewer (read-only). Each route calls the git data layer and maps its {error,status} to an HTTP
+// status (same shape as the docs routes); the layer enforces the under-$HOME containment and validation.
+import express from 'express';
+export function gitRoutes({ git }) {
+    const r = express.Router();
+    const q = (value) => (typeof value === 'string' ? value : '');
+    r.get('/git/repos', async (req, res, next) => {
+        try {
+            const out = await git.detectRepos(q(req.query.dir));
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ repos: out.repos });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/git/status', async (req, res, next) => {
+        try {
+            const out = await git.status(q(req.query.repo));
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ changes: out.changes });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/git/log', async (req, res, next) => {
+        try {
+            const out = await git.log(q(req.query.repo), req.query.limit, req.query.ref ? q(req.query.ref) : undefined);
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ commits: out.commits });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/git/branches', async (req, res, next) => {
+        try {
+            const out = await git.branches(q(req.query.repo));
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ branches: out.branches });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/git/diff', async (req, res, next) => {
+        try {
+            const out = await git.diff(q(req.query.repo), {
+                path: q(req.query.path),
+                commit: req.query.commit ? q(req.query.commit) : undefined,
+                staged: req.query.staged === '1',
+            });
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ diff: out.diff, truncated: out.truncated });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/git/commit', async (req, res, next) => {
+        try {
+            const out = await git.commit(q(req.query.repo), q(req.query.hash));
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            return res.json({ message: out.message, files: out.files });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    return r;
+}

package/dist/src/routes/health.js

@@ -0,0 +1,16 @@
+import express from 'express';
+export function healthRoutes({ health, refresh = () => { }, }) {
+    const router = express.Router();
+    router.get('/health/live', (_req, res) => res.json(health.live()));
+    router.get('/health/ready', async (_req, res, next) => {
+        try {
+            await refresh();
+            const snapshot = health.snapshot();
+            return res.status(snapshot.ready ? 200 : 503).json(snapshot);
+        }
+        catch (error) {
+            return next(error);
+        }
+    });
+    return router;
+}

package/dist/src/routes/notifications.js

@@ -0,0 +1,16 @@
+// Read/delete for the manual-push inbox. Recording happens in routes/push.js (send-local). This
+// module is single-purpose: list history (newest first) and delete one entry by id.
+import express from 'express';
+export function notificationRoutes({ notifications }) {
+    const r = express.Router();
+    r.get('/notifications', (req, res) => {
+        const device = req.query.device;
+        res.json({ items: typeof device === 'string' && device ? notifications.list(device) : [] });
+    });
+    r.delete('/notifications/:id', (req, res) => {
+        const device = req.query.device;
+        const id = req.params.id;
+        res.json({ ok: typeof device === 'string' && device && id ? notifications.remove(device, id) : false });
+    });
+    return r;
+}

package/dist/src/routes/previews.js

@@ -0,0 +1,43 @@
+// Preview registry routes: register a static directory, list, and remove. Each registration returns a
+// runtime-only capability URL; the main Handmux token is never exposed to preview content.
+import express from 'express';
+import { safePreviewName } from '../previews.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function previewRoutes({ previews }) {
+    const r = express.Router();
+    // POST {name,dir} registers a static directory served at /preview/<name>/.
+    r.post('/previews', async (req, res, next) => {
+        if (!previews)
+            return res.status(503).json({ error: 'previews disabled' });
+        const body = req.body;
+        const name = isRecord(body) ? body.name : undefined;
+        const dir = isRecord(body) ? body.dir : undefined;
+        if (typeof name !== 'string' || !name || typeof dir !== 'string' || !dir)
+            return res.status(400).json({ error: 'bad request' });
+        try {
+            const out = await previews.register({ name, dir });
+            if ('error' in out)
+                return res.status(out.status).json({ error: out.error });
+            const url = `/preview/${encodeURIComponent(out.name)}/${encodeURIComponent(out.accessToken)}/`;
+            return res.json({ name: out.name, kind: out.kind, url, expiresAt: out.expiresAt });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.get('/previews', (_req, res) => {
+        if (!previews)
+            return res.status(503).json({ error: 'previews disabled' });
+        return res.json({ previews: previews.list() });
+    });
+    r.delete('/previews/:name', (req, res) => {
+        if (!previews)
+            return res.status(503).json({ error: 'previews disabled' });
+        const name = req.params.name;
+        if (!name || !safePreviewName(name))
+            return res.status(400).json({ error: 'bad name' });
+        previews.remove(name);
+        return res.status(204).end();
+    });
+    return r;
+}

package/dist/src/routes/push.js

@@ -0,0 +1,145 @@
+// Web Push routes: hand the client the VAPID key, store/update/remove a browser PushSubscription, and
+// the local script-push send entry. The push module owns the delivery contract (TTL/topic/prune).
+import express from 'express';
+import { sanitizeNotificationUrl } from '../urlPolicy.js';
+import { parsePushSubscription } from '../push.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const strings = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && item.length > 0)
+    : [];
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export function pushRoutes({ push, notifications }) {
+    const r = express.Router();
+    // The client needs the VAPID public key to subscribe; 503 if the server has no keys configured.
+    r.get('/push/vapid', (_req, res) => {
+        if (!push.isConfigured())
+            return res.status(503).json({ error: 'push not configured' });
+        return res.json({ key: push.publicKey() });
+    });
+    // Store a browser PushSubscription, then immediately fire a welcome push back to it — so enabling
+    // the toggle proves the whole pipe (subscribe → push service → SW → notification) end to end.
+    r.post('/push/subscribe', async (req, res, next) => {
+        const body = req.body;
+        const sub = parsePushSubscription(isRecord(body) ? body.subscription : undefined);
+        const preferredPushKey = isRecord(body) ? body.pushKey : undefined;
+        const boundSessions = strings(isRecord(body) ? body.boundSessions : undefined);
+        if (!sub)
+            return res.status(400).json({ error: 'bad subscription' });
+        try {
+            const pushKey = push.addSubscription(sub, boundSessions, preferredPushKey);
+            if (!pushKey)
+                return res.status(400).json({ error: 'bad subscription' });
+            const delivery = await push.sendToOne(sub, { title: '通知已开启 ✅', body: '会话「需要你」或「已完成」时提醒你', tag: 'handmux-welcome' }, { topic: 'handmux', urgency: 'high' });
+            // `deliver` deliberately contains failures so an automatic pane push can never break the polling
+            // loop. Enabling notifications is different: its welcome push is the end-to-end health check, so a
+            // rejected/dead subscription must not be reported to the phone as "enabled".
+            if (delivery.sent !== 1) {
+                const expired = delivery.gone > 0;
+                return res.status(expired ? 410 : 502).json({
+                    error: expired ? 'push subscription expired' : 'push delivery rejected',
+                });
+            }
+            return res.json({ ok: true, count: push.count(), pushKey });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.post('/push/unsubscribe', (req, res) => {
+        const body = req.body;
+        const endpoint = isRecord(body) ? body.endpoint : undefined;
+        const pushKey = typeof endpoint === 'string' ? push.removeSubscription(endpoint) : null;
+        return res.json({ ok: true, pushKey });
+    });
+    // Manual "send me a test" — pushes to every stored subscription.
+    r.post('/push/test', async (_req, res, next) => {
+        try {
+            const out = await push.sendToAll({ title: 'handmux 测试', body: '这是一条测试通知 — 点我回到 app', tag: 'handmux-test' }, { topic: 'handmux', urgency: 'high' });
+            const { deliveries: _deliveries, ...summary } = out;
+            return res.json(summary);
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // Client reports which sessions this device cares about; updates the stored subscription.
+    r.post('/push/bound', (req, res) => {
+        const requestBody = req.body;
+        const endpoint = isRecord(requestBody) ? requestBody.endpoint : undefined;
+        const boundSessions = strings(isRecord(requestBody) ? requestBody.boundSessions : undefined);
+        if (typeof endpoint === 'string')
+            push.updateBound(endpoint, boundSessions);
+        return res.json({ ok: true });
+    });
+    // Local script push (`handmux push`): loopback + server token. Scope is mutually exclusive —
+    // devices (by pushKey) > sessions > all. This is the ONLY push-send entry; no public/remote variant.
+    r.post('/push/send-local', async (req, res, next) => {
+        const requestBody = req.body;
+        const data = isRecord(requestBody) ? requestBody : {};
+        const { title, body, tag, url } = data;
+        if (typeof title !== 'string' || !title.trim())
+            return res.status(400).json({ error: 'title required' });
+        if (typeof body !== 'string' || !body.trim())
+            return res.status(400).json({ error: 'body required' });
+        const safeUrl = url == null ? null : sanitizeNotificationUrl(url);
+        if (url != null && !safeUrl)
+            return res.status(400).json({ error: 'url must be http(s) or relative' });
+        const sessions = strings(data.sessions);
+        const devices = strings(data.devices);
+        const hasSessions = sessions.length > 0;
+        const hasDevices = devices.length > 0;
+        if (hasSessions && hasDevices)
+            return res.status(400).json({ error: 'use --session or --device, not both' });
+        const payload = { title, body };
+        if (typeof tag === 'string' && tag)
+            payload.tag = tag;
+        const opts = { urgency: 'normal', ttl: 1800 };
+        if (typeof payload.tag === 'string')
+            opts.topic = payload.tag;
+        // Record FIRST so the notification tap can deep-link to this exact message's detail page. `--url`
+        // is stored on the record (surfaced in the detail), NOT used as the tap target.
+        let targetKeys = [];
+        let rec = null;
+        if (notifications) {
+            targetKeys = push.resolveTargetKeys({ devices: hasDevices ? devices : null, sessions: hasSessions ? sessions : null });
+            rec = notifications.record(targetKeys, {
+                title, body, tag: payload.tag, url: safeUrl, delivery: { status: 'pending' },
+            });
+            payload.data = { inboxId: rec.id };
+        }
+        try {
+            const out = hasDevices ? await push.sendToDevices(devices, payload, opts)
+                : hasSessions ? await push.sendToSessions(sessions, payload, opts)
+                    : await push.sendToAll(payload, opts);
+            if (notifications && rec) {
+                for (const delivery of out.deliveries || []) {
+                    if (!delivery.pushKey)
+                        continue;
+                    try {
+                        notifications.updateDelivery(delivery.pushKey, rec.id, delivery);
+                    }
+                    catch (error) {
+                        // Delivery already happened. Do not turn a status-metadata write failure into an HTTP error:
+                        // CLI automation would retry and send the real notification twice. The pending record remains
+                        // honest (unknown final state) and the server log retains the storage failure for diagnosis.
+                        console.warn(`[handmux] notification delivery status update failed: ${errorMessage(error)}`);
+                    }
+                }
+            }
+            const { deliveries: _deliveries, ...summary } = out;
+            return res.json(summary);
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // This device's addressing key (server-token auth) — the script push sheet reads it to show `--device`.
+    r.post('/push/key', (req, res) => {
+        const requestBody = req.body;
+        const endpoint = isRecord(requestBody) ? requestBody.endpoint : undefined;
+        if (typeof endpoint !== 'string')
+            return res.status(400).json({ error: 'endpoint required' });
+        return res.json({ pushKey: push.getPushKey(endpoint) });
+    });
+    return r;
+}