@haowjy/remote-workspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haowjy
+
+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,147 @@
+# Remote Workspace
+
+Mobile-friendly read/upload web workspace for this repository.
+
+## Features
+
+- Browse repository folders/files
+- Upload images into `.clipboard/` at repo root (single image per upload)
+- Delete images from `.clipboard/` and `.playwright-mcp/` from the UI
+- Preview text files and images
+- Render Markdown with Mermaid diagrams
+- Hide and block access to dotfiles/dot-directories (for example `.env`, `.git`)
+- Dedicated collapsible `.clipboard` panel for upload + quick image viewing
+
+This app is intentionally **no text editing** to keep remote access simple and lower risk.
+Image operations are limited to upload/delete with strict filename validation.
+
+## Start
+
+From repo root:
+
+```bash
+pnpm dev
+```
+
+By default it serves on `127.0.0.1:18080`.
+
+The Node launcher configures Tailscale Serve (tailnet-only) by default before starting.
+
+Disable Serve mode (local-only):
+
+```bash
+pnpm dev -- no-serve
+```
+
+Enable Funnel mode (public internet):
+
+```bash
+pnpm dev -- password your-password --funnel
+```
+
+Enable Basic Auth:
+
+```bash
+pnpm dev -- password your-password
+# or
+REMOTE_WS_PASSWORD=your-password pnpm dev -- password
+```
+
+When a password is set and serve mode is not explicitly chosen, the launcher defaults to local-only (`--no-serve`). Add `--serve` if you want password-protected remote access through Tailscale.
+`--funnel` requires password auth and exposes the workspace publicly.
+When this auto-switch happens, the launcher prints a warning with the exact `--serve` override.
+
+Copy/paste startup command:
+
+```bash
+cd /path/to/your/repo && pnpm dev
+```
+
+## Options
+
+```bash
+pnpm dev -- config /path/to/config
+pnpm dev -- port 18111
+pnpm dev -- install
+pnpm dev -- no-serve
+pnpm dev -- password your-password
+pnpm dev -- password your-password --serve
+pnpm dev -- password your-password --funnel
+```
+
+## Environment
+
+- `REMOTE_WS_PORT` (default `18080`)
+- `REMOTE_WS_MAX_PREVIEW_BYTES` (default `1048576`)
+- `REMOTE_WS_MAX_UPLOAD_BYTES` (default `26214400`)
+- `REMOTE_WS_PASSWORD` (optional, enables HTTP Basic Auth when set)
+- `REMOTE_WS_CONFIG_FILE` (optional config file path override)
+- `REPO_ROOT` (injected by launcher script)
+
+Password config file format (default: repo root `.remote-workspace.conf`):
+
+```bash
+REMOTE_WS_PASSWORD=your-password
+```
+
+Password/config precedence:
+
+1. CLI inline password (`--password <pwd>`)
+2. Env password (`REMOTE_WS_PASSWORD`)
+3. Selected config file value (`REMOTE_WS_PASSWORD=...`)
+
+Config file selection precedence:
+
+1. CLI config path (`--config <path>`)
+2. Env config path (`REMOTE_WS_CONFIG_FILE`)
+3. Project config (`<repo-root>/.remote-workspace.conf`)
+4. User config (`$XDG_CONFIG_HOME/remote-workspace/config`, then `$APPDATA/remote-workspace/config`, then `~/.config/remote-workspace/config`)
+
+## Upload Clipboard
+
+- `POST /api/clipboard/upload` always writes to `REPO_ROOT/.clipboard`
+- `DELETE /api/clipboard/file?name=<filename>` deletes one image in `REPO_ROOT/.clipboard`
+- `.clipboard` panel uses dedicated clipboard endpoints (`/api/clipboard/upload`, `/api/clipboard/list`, `/api/clipboard/file`)
+- Main repository browser still blocks all hidden paths and gitignored paths
+- Gitignored paths are hidden/blocked (for example `node_modules/`, build artifacts, local secrets)
+- Accepted upload types are images only (`png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, `bmp`, `heic`, `heif`, `avif`)
+- Clipboard panel supports both file picker and `Paste From Clipboard` button (when browser clipboard image API is available)
+- Upload requires `name` query parameter (filename is user-controlled)
+- Filename rules: no spaces, no leading dot, `[A-Za-z0-9._-]` only, and must use an allowed image extension
+- Multipart field names accepted: `file` (current UI) and `files` (legacy cached UI compatibility)
+- Legacy alias: `/api/upload` is still accepted for older cached clients
+
+## Screenshots
+
+- `GET /api/screenshots/list` lists images in `REPO_ROOT/.playwright-mcp`
+- `GET /api/screenshots/file?name=<filename>` streams one screenshot image
+- `DELETE /api/screenshots/file?name=<filename>` deletes one screenshot image
+
+## Caching
+
+- The browser now caches image bytes (`/api/clipboard/file`, `/api/screenshots/file`, image responses from `/api/file`) with short-lived cache headers and validators.
+- The client keeps a small local metadata cache (tree + clipboard/screenshot lists) and hydrates immediately on reload, then refreshes in the background.
+- Refresh buttons bypass local metadata cache and force a new server fetch.
+
+## Tailscale
+
+Tailscale Serve is enabled by default and stays private to your tailnet.
+Use `--no-serve` if you want local-only mode.
+Use `--funnel` to publish via Tailscale Funnel (password required).
+If Tailscale is missing or disconnected while serve mode is enabled, the launcher exits with guidance to either switch to local-only mode or run `tailscale up` and retry `--serve`.
+
+```bash
+# Tailnet-only URL
+pnpm dev
+```
+
+Manual commands (equivalent):
+
+```bash
+tailscale serve --bg --https=443 127.0.0.1:18080
+```
+
+## Auth
+
+When `REMOTE_WS_PASSWORD` is set (or `--password` is passed to the launcher), the app requires HTTP Basic Auth for all routes (UI + API).
+When auth is enabled, mutating routes (`POST`/`DELETE`) also require same-origin `Origin`/`Referer` headers.

package/dist/launcher.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirectoryPath = path.dirname(currentFilePath);
+const appDir = path.resolve(currentDirectoryPath, "..");
+function printUsage() {
+    console.log(`Usage: pnpm dev -- [options]
+
+Options:
+  --repo-root <path> Repository root to expose (default: REPO_ROOT or cwd)
+  --config <path>    Config file path (default uses precedence search)
+  --port <port>      Listen port (default: REMOTE_WS_PORT or 18080)
+  --install          Force dependency install before start
+  --skip-install     Skip install check even if node_modules is missing
+  --no-serve         Skip tailscale serve setup
+  --funnel           Enable tailscale funnel (public internet)
+  --password [pwd]   Enable Basic Auth (optional inline password)
+  --serve            Force tailscale serve setup
+  -h, --help         Show this help text
+
+Examples:
+  pnpm dev
+  pnpm dev -- --repo-root /path/to/repo
+  pnpm dev -- --config ~/.config/remote-workspace/config
+  pnpm dev -- --port 18111
+  pnpm dev -- --password
+  pnpm dev -- --password mypass --serve
+  pnpm dev -- --password mypass --funnel
+  REMOTE_WS_PASSWORD=mypass pnpm dev -- --password
+`);
+}
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+function parsePort(rawPort) {
+    if (!/^\d+$/.test(rawPort)) {
+        fail(`Invalid --port value: ${rawPort} (must be numeric).`);
+    }
+    const value = Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        fail(`Invalid --port value: ${rawPort} (must be 1-65535).`);
+    }
+    return value;
+}
+function parseConfigPassword(configFilePath) {
+    if (!existsSync(configFilePath)) {
+        return "";
+    }
+    const content = readFileSync(configFilePath, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+        if (/^\s*$/.test(line) || /^\s*#/.test(line)) {
+            continue;
+        }
+        const match = line.match(/^\s*REMOTE_WS_PASSWORD\s*=(.*)$/);
+        if (!match) {
+            continue;
+        }
+        let value = match[1].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        return value;
+    }
+    return "";
+}
+function resolveUserConfigPath() {
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) {
+        return path.resolve(xdgConfigHome, "remote-workspace", "config");
+    }
+    const appData = process.env.APPDATA;
+    if (appData) {
+        return path.resolve(appData, "remote-workspace", "config");
+    }
+    const home = process.env.HOME ??
+        process.env.USERPROFILE ??
+        (process.env.HOMEDRIVE && process.env.HOMEPATH
+            ? `${process.env.HOMEDRIVE}${process.env.HOMEPATH}`
+            : undefined);
+    if (!home) {
+        return "";
+    }
+    return path.resolve(home, ".config", "remote-workspace", "config");
+}
+function parseArgs(argv) {
+    let repoRoot = path.resolve(process.env.REPO_ROOT ?? process.cwd());
+    let port = parsePort(process.env.REMOTE_WS_PORT ?? "18080");
+    let skipInstall = false;
+    let forceInstall = false;
+    let serveEnabled = true;
+    let serveModeSet = false;
+    let funnelEnabled = false;
+    let passwordEnabled = false;
+    let workspacePassword = "";
+    let configFileFromArg = null;
+    let configFile = "";
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--repo-root": {
+                const next = argv[i + 1];
+                if (!next || next.startsWith("--")) {
+                    fail("Missing value for --repo-root.");
+                }
+                repoRoot = path.resolve(next);
+                i += 1;
+                break;
+            }
+            case "--config": {
+                const next = argv[i + 1];
+                if (!next || next.startsWith("--")) {
+                    fail("Missing value for --config.");
+                }
+                configFileFromArg = path.resolve(next);
+                i += 1;
+                break;
+            }
+            case "--port": {
+                const next = argv[i + 1];
+                if (!next || next.startsWith("--")) {
+                    fail("Missing value for --port.");
+                }
+                port = parsePort(next);
+                i += 1;
+                break;
+            }
+            case "--install":
+                forceInstall = true;
+                break;
+            case "--skip-install":
+                skipInstall = true;
+                break;
+            case "--no-serve":
+                serveEnabled = false;
+                funnelEnabled = false;
+                serveModeSet = true;
+                break;
+            case "--funnel":
+                serveEnabled = true;
+                funnelEnabled = true;
+                serveModeSet = true;
+                break;
+            case "--password": {
+                passwordEnabled = true;
+                const maybeValue = argv[i + 1];
+                if (maybeValue && !maybeValue.startsWith("--")) {
+                    workspacePassword = maybeValue;
+                    i += 1;
+                }
+                break;
+            }
+            case "--serve":
+                serveEnabled = true;
+                funnelEnabled = false;
+                serveModeSet = true;
+                break;
+            case "-h":
+            case "--help":
+                printUsage();
+                process.exit(0);
+            default:
+                fail(`Unknown argument: ${arg}`);
+        }
+    }
+    if (!existsSync(repoRoot)) {
+        fail(`Repository root does not exist: ${repoRoot}`);
+    }
+    const projectConfigFile = path.resolve(repoRoot, ".remote-workspace.conf");
+    const userConfigFile = resolveUserConfigPath();
+    if (configFileFromArg) {
+        if (!existsSync(configFileFromArg)) {
+            fail(`Config file does not exist: ${configFileFromArg}`);
+        }
+        configFile = configFileFromArg;
+    }
+    else if (process.env.REMOTE_WS_CONFIG_FILE) {
+        const envConfigFile = path.resolve(process.env.REMOTE_WS_CONFIG_FILE);
+        if (!existsSync(envConfigFile)) {
+            fail(`Config file from REMOTE_WS_CONFIG_FILE does not exist: ${envConfigFile}`);
+        }
+        configFile = envConfigFile;
+    }
+    else if (existsSync(projectConfigFile)) {
+        configFile = projectConfigFile;
+    }
+    else if (userConfigFile && existsSync(userConfigFile)) {
+        configFile = userConfigFile;
+    }
+    else {
+        // No discovered config file. Keep the conventional project path for messages.
+        configFile = projectConfigFile;
+    }
+    const configPassword = parseConfigPassword(configFile);
+    if (!workspacePassword) {
+        workspacePassword =
+            process.env.REMOTE_WS_PASSWORD ?? configPassword;
+    }
+    // Backward compatibility: explicit env password enables auth without flag.
+    if (!passwordEnabled && Boolean(process.env.REMOTE_WS_PASSWORD)) {
+        passwordEnabled = true;
+    }
+    if (passwordEnabled && !workspacePassword) {
+        fail(`--password was provided but no password value is available.\nSet REMOTE_WS_PASSWORD, pass --password <pwd>, or create ${configFile} with REMOTE_WS_PASSWORD=...`);
+    }
+    if (!passwordEnabled) {
+        workspacePassword = "";
+    }
+    if (funnelEnabled && !passwordEnabled) {
+        fail(`--funnel requires password auth.\nPass --password (or set REMOTE_WS_PASSWORD / ${configFile}).`);
+    }
+    if (!serveModeSet && passwordEnabled) {
+        serveEnabled = false;
+        console.warn("Warning: password auth is enabled and no serve mode was selected.\nDefaulting to local-only mode (--no-serve).\nTo expose through Tailscale, restart with --serve.");
+    }
+    return {
+        repoRoot,
+        port,
+        skipInstall,
+        forceInstall,
+        serveEnabled,
+        serveModeSet,
+        funnelEnabled,
+        passwordEnabled,
+        workspacePassword,
+        configFile,
+    };
+}
+function hasCommand(commandName) {
+    const locator = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(locator, [commandName], { stdio: "ignore" });
+    return result.status === 0;
+}
+function runSyncOrFail(commandName, args, message) {
+    const result = spawnSync(commandName, args, { stdio: "inherit" });
+    if (result.error) {
+        fail(`${message}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        fail(message);
+    }
+}
+function runSync(commandName, args) {
+    spawnSync(commandName, args, { stdio: "inherit" });
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!hasCommand("pnpm")) {
+        fail("pnpm is required but not installed.");
+    }
+    if (args.serveEnabled) {
+        if (!hasCommand("tailscale")) {
+            fail("tailscale is not installed, but serve mode is enabled.\nUse local-only mode: pnpm dev -- --no-serve (or pnpm dev -- --password <pwd>).\nOr install Tailscale, run 'tailscale up', then restart with --serve.");
+        }
+        runSyncOrFail("tailscale", ["status"], "tailscale is installed but not connected.\nRun 'tailscale up' and retry --serve, or use local-only mode with --no-serve.");
+    }
+    if (!existsSync(path.join(appDir, "package.json"))) {
+        fail(`remote-workspace app not found at: ${appDir}`);
+    }
+    if (args.forceInstall) {
+        runSyncOrFail("pnpm", ["--dir", appDir, "install"], "Dependency install failed.");
+    }
+    else if (!args.skipInstall && !existsSync(path.join(appDir, "node_modules"))) {
+        runSyncOrFail("pnpm", ["--dir", appDir, "install"], "Dependency install failed.");
+    }
+    if (args.serveEnabled) {
+        console.log(`Configuring tailscale serve (https:443 -> 127.0.0.1:${args.port})`);
+        runSyncOrFail("tailscale", ["serve", "--bg", "--https=443", `127.0.0.1:${args.port}`], "tailscale serve setup failed.");
+        if (args.funnelEnabled) {
+            console.log("Enabling tailscale funnel (public internet exposure)");
+            runSyncOrFail("tailscale", ["funnel", "--bg", "on"], "tailscale funnel setup failed.");
+            runSync("tailscale", ["funnel", "status"]);
+        }
+        else {
+            runSync("tailscale", ["serve", "status"]);
+        }
+    }
+    else {
+        console.log("Skipping tailscale serve (--no-serve).");
+    }
+    console.log(`Starting remote-workspace on http://127.0.0.1:${args.port}`);
+    console.log(`Repo root: ${args.repoRoot}`);
+    if (args.passwordEnabled) {
+        console.log("Auth: Basic Auth enabled");
+    }
+    console.log("");
+    const child = spawn("pnpm", ["--dir", appDir, "dev:server"], {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            REPO_ROOT: args.repoRoot,
+            REMOTE_WS_PORT: String(args.port),
+            REMOTE_WS_PASSWORD: args.workspacePassword,
+        },
+    });
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 1);
+    });
+}
+main();