folderview 0.0.0-stage → 0.2.1

package/dist/client/index.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="theme-color" content="#f8f8fb" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#16171c" media="(prefers-color-scheme: dark)" />
+    <title>folderview</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' rx='8' fill='%235b5fd6'/><path d='M12 10l-6 6 6 6M20 10l6 6-6 6' fill='none' stroke='white' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'/></svg>" />
+    <link rel="stylesheet" href="assets/app.css" />
+    <script>
+      // the saved theme before anything draws, so a dark page never flashes white
+      try {
+        const t = localStorage.getItem('folderview:theme');
+        if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t;
+      } catch {}
+    </script>
+  </head>
+  <body>
+    <div class="shell">
+      <header class="bar" id="bar">
+        <button class="brand" id="home" title="Back to the top folder">
+          <span class="logo"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path d="m8 7-5 5 5 5M16 7l5 5-5 5" /></svg></span><b id="repo">…</b>
+        </button>
+        <span id="branch"></span>
+        <form class="search" id="search-form" role="search">
+          <span id="search-icon"></span>
+          <input id="q" type="search" placeholder="Search in files" aria-label="Search in files" autocomplete="off" spellcheck="false" enterkeyhint="search" />
+          <button type="button" class="chip" id="scope">everywhere</button>
+        </form>
+        <nav class="bar-acts">
+          <button class="icon-btn" id="qo-btn" title="Go to a file (Ctrl+P)" aria-label="Go to a file"></button>
+          <button class="icon-btn" data-nav="changes" id="changes-btn" title="What changed since the last commit" aria-label="Changes" hidden><span class="count" id="changes-count" hidden>0</span></button>
+          <button class="icon-btn" data-nav="review" id="review-btn" title="Review comments" aria-label="Review"><span class="count warn" id="review-count" hidden>0</span></button>
+          <button class="icon-btn" id="settings-btn" title="Settings" aria-label="Settings"></button>
+          <span class="live" id="live" title="Live: updates as files change"></span>
+        </nav>
+      </header>
+      <div class="app" id="app">
+        <aside class="tree" aria-label="Folders"><ul class="roots" id="tree"></ul></aside>
+        <div class="splitter-wrap"><div class="splitter" id="splitter" title="Drag to resize"></div></div>
+        <section class="main" id="main" aria-label="Folder"></section>
+        <section class="file" id="file" aria-label="File" hidden></section>
+      </div>
+    </div>
+    <script type="module" src="assets/main.js"></script>
+  </body>
+</html>

package/dist/config.js

@@ -0,0 +1,322 @@
+// Settings from, highest first: command-line flags, environment variables, the folder's .folderviewrc.json, the user's
+// config file ($XDG_CONFIG_HOME/folderview/config.json, ~/.config/folderview/config.json), then defaults.
+// Exclude patterns add up from every source, plus the folder's .folderviewignore.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const DEFAULTS = {
+    root: '.',
+    port: 4190,
+    host: '127.0.0.1',
+    base: '/',
+    open: false,
+    exclude: [],
+    hide: [],
+    showSecrets: false,
+    git: true,
+    watch: true,
+    readOnly: false,
+    allowHosts: [],
+    token: '',
+    reviewDir: '.review',
+    title: '',
+    author: '',
+    maxFileMb: 5,
+};
+/** The environment variable for each setting. */
+export const ENV = {
+    FOLDERVIEW_ROOT: 'root',
+    FOLDERVIEW_PORT: 'port',
+    FOLDERVIEW_HOST: 'host',
+    FOLDERVIEW_BASE: 'base',
+    FOLDERVIEW_OPEN: 'open',
+    FOLDERVIEW_EXCLUDE: 'exclude',
+    FOLDERVIEW_HIDE: 'hide',
+    FOLDERVIEW_SHOW_SECRETS: 'showSecrets',
+    FOLDERVIEW_GIT: 'git',
+    FOLDERVIEW_WATCH: 'watch',
+    FOLDERVIEW_READ_ONLY: 'readOnly',
+    FOLDERVIEW_ALLOW_HOSTS: 'allowHosts',
+    FOLDERVIEW_TOKEN: 'token',
+    FOLDERVIEW_REVIEW_DIR: 'reviewDir',
+    FOLDERVIEW_TITLE: 'title',
+    FOLDERVIEW_AUTHOR: 'author',
+    FOLDERVIEW_MAX_FILE_MB: 'maxFileMb',
+};
+export const HELP = `folderview: browse, search and review a folder in your browser
+
+Usage: folderview [folder] [options]
+       folderview review [folder] [--all] [--json]   print the review comments (open ones, unless --all)
+
+  folder                  the folder to serve (default: the current folder)
+  -p, --port <n>          port to try first (default 4190; the next free one is used)
+  -H, --host <addr>       address to listen on (default 127.0.0.1)
+      --lan               listen on every interface (same as --host 0.0.0.0)
+      --base <path>       serve under a URL path, e.g. /code/ (behind a proxy)
+  -o, --open              open it in your browser
+  -x, --exclude <globs>   never show, serve or search these (comma-separated, repeatable):
+                          "*.log,dist/,/secrets,**/*.min.js"
+      --hide <names>      exact names to hide everywhere (.git always is)
+      --show-secrets      show .env, *.key, *.pem and id_rsa files (hidden by default)
+      --token <t>         require this token (open ?token=… once; it's kept as a cookie)
+      --allow-host <h>    accept this host name too, e.g. a tunnel's (repeatable; * for any)
+      --review-dir <dir>  where review comments are saved (default .review)
+      --title <name>      the name shown at the top
+      --author <name>     the default name on comments
+      --max-file-mb <n>   bigger files aren't previewed as text or searched (default 5)
+      --read-only         nobody can add comments
+      --no-git            don't use git
+      --no-watch          no live updates
+      --print-config      show the settings and where each came from, then exit
+  -v, --version
+  -h, --help
+
+Every option also reads from an environment variable (FOLDERVIEW_PORT, FOLDERVIEW_HOST,
+FOLDERVIEW_EXCLUDE, FOLDERVIEW_TOKEN, …), from .folderviewrc.json in the folder, and from
+~/.config/folderview/config.json. Patterns in the folder's .folderviewignore are excluded too.`;
+const LIST_KEYS = new Set(['exclude', 'hide', 'allowHosts']);
+const NUM_KEYS = new Set(['port', 'maxFileMb']);
+function bool(v) {
+    return !/^(0|false|no|off)$/i.test(v.trim());
+}
+function list(v) {
+    if (Array.isArray(v))
+        return v.map(String).flatMap((s) => s.split(',')).map((s) => s.trim()).filter(Boolean);
+    if (typeof v === 'string')
+        return v
+            .split(/[,\n]/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return [];
+}
+export class ConfigError extends Error {
+}
+function readJson(file) {
+    if (!fs.existsSync(file))
+        return undefined;
+    try {
+        const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            throw new Error('not an object');
+        return Object.fromEntries(Object.entries(data).filter(([k]) => k in DEFAULTS));
+    }
+    catch (e) {
+        throw new ConfigError(`${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+export function globalConfigPath(env = process.env) {
+    if (env['FOLDERVIEW_CONFIG'])
+        return path.resolve(env['FOLDERVIEW_CONFIG']);
+    const base = env['XDG_CONFIG_HOME'] || path.join(os.homedir(), '.config');
+    return path.join(base, 'folderview', 'config.json');
+}
+/** Flags → a partial set of settings (no defaults yet). */
+function parseFlags(argv) {
+    const raw = {};
+    const add = (k, v) => {
+        raw[k] = [...list(raw[k]), ...list(v)];
+    };
+    let help = false, version = false, printConfig = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+        const flag = eq > 0 ? a.slice(0, eq) : a;
+        const inline = eq > 0 ? a.slice(eq + 1) : undefined;
+        const value = () => {
+            const v = inline ?? argv[++i];
+            if (v === undefined)
+                throw new ConfigError(`${flag} needs a value`);
+            return v;
+        };
+        switch (flag) {
+            case '-h':
+            case '--help':
+                help = true;
+                break;
+            case '-v':
+            case '--version':
+                version = true;
+                break;
+            case '--print-config':
+                printConfig = true;
+                break;
+            case '-p':
+            case '--port':
+                raw.port = value();
+                break;
+            case '-H':
+            case '--host':
+                raw.host = value();
+                break;
+            case '--lan':
+                raw.host = '0.0.0.0';
+                break;
+            case '--base':
+                raw.base = value();
+                break;
+            case '-o':
+            case '--open':
+                raw.open = true;
+                break;
+            case '-x':
+            case '--exclude':
+                add('exclude', value());
+                break;
+            case '--hide':
+                add('hide', value());
+                break;
+            case '--show-secrets':
+                raw.showSecrets = true;
+                break;
+            case '--token':
+                raw.token = value();
+                break;
+            case '--allow-host':
+                add('allowHosts', value());
+                break;
+            case '--review-dir':
+                raw.reviewDir = value();
+                break;
+            case '--title':
+                raw.title = value();
+                break;
+            case '--author':
+                raw.author = value();
+                break;
+            case '--max-file-mb':
+                raw.maxFileMb = value();
+                break;
+            case '--read-only':
+                raw.readOnly = true;
+                break;
+            case '--no-git':
+                raw.git = false;
+                break;
+            case '--no-watch':
+                raw.watch = false;
+                break;
+            default:
+                if (a.startsWith('-') && a !== '-')
+                    throw new ConfigError(`Unknown option ${a} (see --help)`);
+                if (raw.root !== undefined)
+                    throw new ConfigError(`Only one folder, please (got ${String(raw.root)} and ${a})`);
+                raw.root = a;
+        }
+    }
+    return { raw, help, version, printConfig };
+}
+function fromEnv(env) {
+    const raw = {};
+    for (const [name, key] of Object.entries(ENV)) {
+        const v = env[name];
+        if (v !== undefined && v !== '')
+            raw[key] = v;
+    }
+    return raw;
+}
+export function resolve(argv, env = process.env, cwd = process.cwd()) {
+    const flags = parseFlags(argv);
+    const envRaw = fromEnv(env);
+    const rootArg = flags.raw.root ?? envRaw.root;
+    const root = path.resolve(cwd, typeof rootArg === 'string' ? rootArg : '.');
+    const globalFile = globalConfigPath(env);
+    const projectFile = path.join(root, '.folderviewrc.json');
+    const globalRaw = readJson(globalFile);
+    const projectRaw = readJson(projectFile);
+    const layers = [
+        ['default', DEFAULTS],
+        [globalFile, globalRaw],
+        [projectFile, projectRaw],
+        ['environment', envRaw],
+        ['command line', flags.raw],
+    ];
+    const sources = {};
+    const merged = {};
+    for (const [source, layer] of layers) {
+        if (!layer)
+            continue;
+        for (const [k, v] of Object.entries(layer)) {
+            if (v === undefined)
+                continue;
+            if (LIST_KEYS.has(k)) {
+                // lists add up across sources
+                const items = list(v);
+                if (!items.length && source !== 'default')
+                    continue;
+                merged[k] = [...list(merged[k]), ...items];
+                if (items.length)
+                    sources[k] = sources[k] && sources[k] !== 'default' ? `${sources[k]} + ${source}` : source;
+                else
+                    sources[k] ??= source;
+                continue;
+            }
+            merged[k] = v;
+            sources[k] = source;
+        }
+    }
+    const ignoreFile = path.join(root, '.folderviewignore');
+    if (fs.existsSync(ignoreFile)) {
+        const lines = fs.readFileSync(ignoreFile, 'utf8').split(/\r?\n/);
+        const pats = lines.map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+        if (pats.length) {
+            merged['exclude'] = [...list(merged['exclude']), ...pats];
+            sources['exclude'] = (sources['exclude'] && sources['exclude'] !== 'default' ? sources['exclude'] + ' + ' : '') + ignoreFile;
+        }
+    }
+    const get = (k) => merged[k];
+    const num = (k) => {
+        const n = Number(get(k));
+        if (!Number.isFinite(n) || n < 0)
+            throw new ConfigError(`${k} must be a number (got ${String(get(k))}, from ${sources[k]})`);
+        return n;
+    };
+    const bl = (k) => {
+        const v = get(k);
+        return typeof v === 'boolean' ? v : bool(String(v));
+    };
+    for (const k of NUM_KEYS)
+        num(k);
+    const port = num('port');
+    if (!Number.isInteger(port) || port > 65535)
+        throw new ConfigError(`port must be 0–65535 (got ${port})`);
+    let base = String(get('base') || '/').trim();
+    if (!base.startsWith('/'))
+        base = '/' + base;
+    if (!base.endsWith('/'))
+        base += '/';
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+        throw new ConfigError(`No such folder: ${root}`);
+    const settings = {
+        root,
+        port,
+        host: String(get('host')),
+        base,
+        open: bl('open'),
+        exclude: list(get('exclude')),
+        hide: list(get('hide')),
+        showSecrets: bl('showSecrets'),
+        git: bl('git'),
+        watch: bl('watch'),
+        readOnly: bl('readOnly'),
+        allowHosts: list(get('allowHosts')),
+        token: String(get('token') ?? ''),
+        reviewDir: String(get('reviewDir')),
+        title: String(get('title') ?? ''),
+        author: String(get('author') ?? ''),
+        maxFileMb: num('maxFileMb'),
+        sources,
+        configFiles: [globalRaw ? globalFile : '', projectRaw ? projectFile : '', fs.existsSync(ignoreFile) ? ignoreFile : ''].filter(Boolean),
+    };
+    return { settings, help: flags.help, version: flags.version, printConfig: flags.printConfig };
+}
+/** The settings as text, with secrets masked and where each came from. */
+export function describe(s) {
+    const rows = Object.keys(DEFAULTS).map((k) => {
+        let v = s[k];
+        if (k === 'token' && v)
+            v = '••••••';
+        const shown = Array.isArray(v) ? (v.length ? v.join(', ') : '(none)') : v === '' ? '(none)' : String(v);
+        return `  ${k.padEnd(12)} ${shown.padEnd(36)} ${s.sources[k] ?? 'default'}`;
+    });
+    return ['folderview settings:', ...rows].join('\n');
+}

package/dist/files.js

@@ -0,0 +1,178 @@
+// Paths inside the served folder, what is hidden, folder listings and raw file serving (with ranges).
+import fs from 'node:fs';
+import path from 'node:path';
+/** Folders a search or a file list skips when git can't say what is ignored. */
+export const NOISE = new Set(['node_modules', '.git', '.hg', '.svn', '.next', '.cache', '.turbo', '__pycache__', '.venv']);
+export function isSecret(name) {
+    if (name.startsWith('.env') && name !== '.env.example' && name !== '.env.sample')
+        return true;
+    if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(name))
+        return true;
+    return /\.(key|pem|p12|pfx|keystore)$/i.test(name);
+}
+export function isHidden(scope, name) {
+    return scope.hidden.has(name) || (scope.hideSecrets && isSecret(name));
+}
+/** A root-relative path with forward slashes, no leading slash. */
+export function toRel(scope, abs) {
+    return path.relative(scope.root, abs).split(path.sep).join('/');
+}
+/** The absolute path for a root-relative one, or undefined when it leaves the root or touches something hidden. */
+export function inside(scope, rel) {
+    const clean = rel.replace(/\\/g, '/');
+    const abs = path.resolve(scope.root, '.' + path.sep + clean);
+    if (abs !== scope.root && !abs.startsWith(scope.root + path.sep))
+        return undefined;
+    const parts = path.relative(scope.root, abs).split(path.sep).filter(Boolean);
+    if (parts.some((p) => isHidden(scope, p)))
+        return undefined;
+    if (parts.length && scope.excluded(parts.join('/')))
+        return undefined;
+    // a link may point outside the root: follow it and check again
+    try {
+        const real = fs.realpathSync(abs);
+        const realRoot = fs.realpathSync(scope.root);
+        if (real !== realRoot && !real.startsWith(realRoot + path.sep))
+            return undefined;
+    }
+    catch {
+        // missing files are fine here (a deleted file's diff); the caller checks existence
+    }
+    return abs;
+}
+export function list(scope, rel) {
+    const abs = inside(scope, rel);
+    if (abs === undefined)
+        return undefined;
+    let dirents;
+    try {
+        dirents = fs.readdirSync(abs, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    return dirents
+        .filter((e) => {
+        if (isHidden(scope, e.name))
+            return false;
+        const dir = toRel(scope, abs);
+        return !scope.excluded(dir ? dir + '/' + e.name : e.name, e.isDirectory());
+    })
+        .flatMap((e) => {
+        try {
+            const st = fs.statSync(path.join(abs, e.name));
+            const entry = { name: e.name, type: st.isDirectory() ? 'folder' : 'file', size: st.size, mtime: st.mtimeMs };
+            if (e.isSymbolicLink())
+                entry.link = true;
+            return [entry];
+        }
+        catch {
+            return []; // a broken link, or removed while listing
+        }
+    });
+}
+export const RAW_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    svg: 'image/svg+xml',
+    ico: 'image/x-icon',
+    bmp: 'image/bmp',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    wav: 'audio/wav',
+    flac: 'audio/flac',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    opus: 'audio/ogg',
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    webm: 'video/webm',
+    ogv: 'video/ogg',
+    mov: 'video/quicktime',
+    pdf: 'application/pdf',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+    json: 'application/json; charset=utf-8',
+    wasm: 'application/wasm',
+};
+/** Any file the page shows: never run as a page on this origin (except a sandboxed HTML preview). */
+const RAW_CSP = "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; media-src 'self'; font-src 'self'";
+/** An HTML preview: sandboxed (no scripts, its own origin), may load its own images and styles. */
+const PREVIEW_CSP = "sandbox; default-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'none'";
+export function serveRaw(scope, rel, req, res, asPage) {
+    const abs = inside(scope, rel);
+    let st;
+    try {
+        st = abs === undefined ? undefined : fs.statSync(abs);
+    }
+    catch {
+        st = undefined;
+    }
+    if (abs === undefined || st === undefined || !st.isFile()) {
+        res.writeHead(404, { 'content-type': 'text/plain' }).end('not found');
+        return;
+    }
+    const ext = path.extname(abs).slice(1).toLowerCase();
+    const type = asPage && /^html?$/.test(ext) ? 'text/html; charset=utf-8' : (RAW_TYPES[ext] ?? 'text/plain; charset=utf-8');
+    const headers = {
+        'content-type': type,
+        'cache-control': 'no-store',
+        'accept-ranges': 'bytes',
+        'x-content-type-options': 'nosniff',
+        'content-security-policy': asPage ? PREVIEW_CSP : RAW_CSP,
+    };
+    const range = /^bytes=(\d*)-(\d*)$/.exec(String(req.headers.range ?? ''));
+    if (range && (range[1] || range[2])) {
+        let start = range[1] ? Number(range[1]) : Math.max(0, st.size - Number(range[2]));
+        let end = range[1] && range[2] ? Number(range[2]) : st.size - 1;
+        end = Math.min(end, st.size - 1);
+        if (start > end || start >= st.size) {
+            res.writeHead(416, { 'content-range': `bytes */${st.size}` }).end();
+            return;
+        }
+        start = Math.max(0, start);
+        res.writeHead(206, { ...headers, 'content-range': `bytes ${start}-${end}/${st.size}`, 'content-length': String(end - start + 1) });
+        if (req.method === 'HEAD')
+            return void res.end();
+        fs.createReadStream(abs, { start, end }).pipe(res);
+        return;
+    }
+    res.writeHead(200, { ...headers, 'content-length': String(st.size) });
+    if (req.method === 'HEAD')
+        return void res.end();
+    fs.createReadStream(abs).pipe(res);
+}
+/** Every file under the root (root-relative), skipping hidden names and the usual noise folders. */
+export function walk(scope, limit = 200_000) {
+    const out = [];
+    const stack = [''];
+    while (stack.length && out.length < limit) {
+        const rel = stack.pop() ?? '';
+        let dirents;
+        try {
+            dirents = fs.readdirSync(path.join(scope.root, rel), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const d of dirents) {
+            if (isHidden(scope, d.name) || NOISE.has(d.name))
+                continue;
+            const p = rel ? rel + '/' + d.name : d.name;
+            if (scope.excluded(p, d.isDirectory()))
+                continue;
+            if (d.isDirectory())
+                stack.push(p);
+            else if (d.isFile())
+                out.push(p);
+        }
+    }
+    return out.sort();
+}