@hardikg/mdview 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] — 2026-08-24
+
+### Fixed
+- Live reload stopped working for any URL that named a file without its root id — a bookmark from before 0.8.0, or the VS Code extension sending a workspace-relative path. Such a request resolves against the primary root and the server answers with the workspace-scoped path, but the page kept comparing watch events against the path it had asked for, so nothing ever matched and the document silently stopped updating on save. The comparison now uses the path the server actually served. The first load always worked, which is why this got past the 0.8.0 checks.
+
+## [0.8.0] — 2026-08-24
+
+One background server, many folders. `mdview <path>` no longer holds the terminal.
+
+### Added
+- **`mdview <path>` returns the shell.** It starts one detached background server the first time it's needed; every later `mdview <path>`, in any repo, adds that folder to the same server and opens it. So unrelated folders — `~/work/api/docs` and `~/notes` — can be read side by side in one window at one stable URL. `--foreground` (`-f`) runs a server in the terminal as before.
+- `mdview ls` (open folders, server pid/port, log path), `mdview rm <name|path>…` (stop serving a folder), `mdview stop` (stop the server).
+- Folders persist in `~/.config/mdview/workspace.json` until removed, across restarts and reboots. Capped at 8, because each holds a live recursive watcher. Opening a file or subfolder inside an already-open folder reuses it instead of adding a duplicate.
+- The background server runs until `mdview stop` or a reboot. `MDVIEW_IDLE_TIMEOUT` opts into having it exit after that many minutes with no browser tab connected (it clears its record, and the next `mdview` starts it again) — off by default, since a server that stays put keeps the URL reliable.
+- `--port` and `--palette` now imply `--foreground`: each overrides a setting belonging to a whole server, and the background one is shared. A useful side effect is that every invocation that worked before behaves exactly as it did — only the bare `mdview [path]` form changed.
+- The printed and opened URL is now `http://mdview.localhost:7331/` instead of `http://127.0.0.1:7331/`. `*.localhost` is reserved to loopback by RFC 6761 and resolves with no setup, no `/etc/hosts` entry and no privileges; the server still binds `127.0.0.1` only. If the local resolver doesn't answer the name with a loopback address the CLI falls back to the literal address rather than printing a URL that could leave the machine. `--vscode` keeps `127.0.0.1` unconditionally, because the extension validates that exact prefix.
+- `PORT` is honoured as the default port when `--port` is omitted, so mdview runs unchanged under a local reverse proxy such as [portless](https://github.com/vercel-labs/portless) for a port-free URL. Invalid values are ignored rather than fatal.
+
+### Changed
+- **Paths in URLs are now workspace-scoped**: `?file=docs/api.md` becomes `?file=<rootId>/docs/api.md`, and asset URLs become `/__asset/<rootId>/<path>`. This is what lets one server host several unrelated folders at once. An unprefixed path still resolves against the first root, so existing links and existing bookmarks keep working, as does the VS Code extension.
+- `/api/tree` now returns `{ roots, tree, config }`. With a single root its contents stay at the top level exactly as before; a second root is what introduces a folder node per root. Window-level settings (palette, font, line width) come from the first root; `ignore` stays per-root.
+- Folder search covers every open folder root and labels each hit with its root. The 200-hit cap is a budget for the whole search rather than per root.
+- With more than one folder open the sidebar groups each under its own heading, expanded by default. `⌘P` and folder search span every folder and show which one each result is in. Live reload learns a `workspace` event, so a folder opened or closed elsewhere appears in tabs that are already open without a reload. Closing the last folder shows an empty state rather than an endless skeleton.
+
+### Security
+- There is deliberately **no HTTP endpoint that changes which folders are served**. The CLI writes `workspace.json` and the server watches it, so adding a root requires filesystem access, which a web page does not have — nothing to CSRF, and no shared token to store or leak. `/api/health` is read-only and reports ids, a pid and a start time, never absolute paths.
+- `mdview stop` checks the recorded pid **and** its start time against what the process reports before signalling it, so a recycled pid belonging to an unrelated process is never killed.
+- State files are written `0600` inside a `0700` directory, each through a temp file and one rename so a reader never sees a half-written file. `workspace.json` is validated defensively on read: a hand-edited or truncated file degrades to fewer folders, never to a crash or an unchecked path.
+- Concurrent `mdview` invocations are serialised through a lock file, so two shells can't race into two servers fighting over the port.
+- Every request's `Host` header is now checked against a loopback allow-list (`localhost`, `*.localhost`, the loopback literals) in an `onRequest` hook, and anything else gets a bare `403`. Closes a DNS-rebinding hole: binding `127.0.0.1` never stopped a page the user was already browsing from re-resolving its own domain to loopback and reading every file mdview serves. Verified against a running server — `Host: evil.com` returned `200` before this change.
+- `@fastify/static` 9 → 10 (major). Closes two high-severity advisories in the component that serves the SPA: authorization bypass via non-canonical URL paths (GHSA-8pvw-jcv7-9cmj) and route-guard bypass via path traversal (GHSA-83w8-p2f5-377r). The plugin is registered at a single call site with a `root` + `prefix` only, and v10 changes nothing we use — its diff against v9 is `fastify-plugin` ^5 → ^6 and `content-disposition` ^1 → ^2.
+- Lockfile-only bumps clearing five further high-severity shipped-dep advisories: `brace-expansion` (DoS via unbounded expansion), `fast-uri` (host confusion via backslash authority delimiter), `find-my-way` (HTTP/2 DoS), `js-yaml` (quadratic CPU in `!!omap`), `linkify-it` (quadratic `mailto:` scan). `npm audit --omit=dev` is back to zero.
+- The one remaining advisory is the `low`, dev-only `esbuild` one already deferred in 0.7.1: it is reachable only through `tsup`/`vite`, is absent from shipped deps, and never enters the published tarball. `npm audit fix` still cannot resolve it without a breaking parent bump.
+
+## [0.7.1] — 2026-07-01
+
+### Security
+- Dependency security bumps applied via `npm audit fix` (lockfile-only, SemVer-compatible — no `package.json` range changes): `markdown-it`, `dompurify`, `linkify-it`, `js-yaml`, `ws`, and dev tooling. Clears all shipped-dep advisories (moderate/high DoS & complexity issues in the render path). One `low`, dev-only `esbuild` advisory (reachable solely through `tsup`'s Windows dev server, never in the published package) has no non-breaking fix and is knowingly deferred; the quality gate now audits shipped deps only (`npm audit --omit=dev`).
+
+### Changed
+- Under `--vscode`, the HTML response now **omits** the `frame-ancestors` CSP directive entirely (previously `frame-ancestors *`). Chromium 142 (shipped in VS Code 1.126) narrowed `frame-ancestors *` to match only network-scheme origins (`http`/`https`/`ws`/`wss`), which excludes the webview's non-network `vscode-webview:` parent — so `*` blocked the extension from framing the preview at all. No CSP value can name the dynamic webview origin, so the directive is dropped in embed mode; the loopback bind (`127.0.0.1`) remains the real network boundary. Default browser runs still emit `frame-ancestors 'none'` byte-for-byte.
+
+### Fixed
+- **Narrow-width layout.** The file-tree and outline panes now collapse into overlay drawers at narrow viewport widths instead of leaving blank, full-width grid columns that squeezed the document into an unreadable vertical sliver. Root cause: the pane-width CSS variables are set inline on `.app-shell` (needed for the drag-resizers), and inline styles overrode the responsive `@media` zeroing; the breakpoints now win via `!important`. Affects the plain browser CLI and the VS Code webview alike.
+- **Embed mode** no longer reserves a blank left column for the (never-rendered) file tree, and the outline now opens correctly in the narrow VS Code preview instead of appearing empty.
+
 ## [0.7.0] — 2026-05-28
 
 CLI prereqs for an upcoming VS Code extension. New, additive surface — browser-mode runs are unchanged.

package/README.md

@@ -50,26 +50,92 @@ node bin/mdview.mjs ./docs
 ### Share with friends without publishing
 
 ```bash
-npm run build && npm pack    # produces mdview-0.6.0.tgz
+npm run build && npm pack    # produces hardikg-mdview-<version>.tgz
 ```
 
 Send them the `.tgz` (Slack/Drive/AirDrop). They install with:
 
 ```bash
-npm install -g ./mdview-0.6.0.tgz
+npm install -g ./hardikg-mdview-<version>.tgz
 ```
 
 ## Usage
 
 ```bash
-mdview <path>              # file or folder
+mdview <path>              # open a file or folder; the shell comes straight back
 mdview                     # current directory
-mdview --port 9000         # custom port (default 7331; auto-fallback unless --port is explicit)
+mdview ls                  # what's open, and where the server is
+mdview rm <name>           # stop serving a folder
+mdview stop                # stop the background server
+mdview --foreground        # run in this terminal instead (Ctrl-C to stop)
 mdview --no-open           # don't auto-launch the browser
+mdview --port 9000         # one-off server on a specific port (implies --foreground)
+mdview --palette nord      # palette for this run (implies --foreground)
 mdview --help              # show usage
 ```
 
-Closes when you `Ctrl-C` or `kill` the process. Set `MDVIEW_DEBUG=1` for full stack traces on unexpected errors.
+### One server, many folders
+
+`mdview` does not hold your terminal. It starts a single background server the
+first time you need one, and every later `mdview <path>` — in any repo — adds
+that folder to the same server and opens it. So you can read
+`~/work/api/docs` and `~/notes` side by side in one window, with one stable
+URL, whether or not the folders are anywhere near each other.
+
+```console
+$ mdview ~/work/api
+mdview → http://mdview.localhost:7331/?root=api
+added: /Users/you/work/api (api)
+$ cd ~/notes && mdview .
+mdview → http://mdview.localhost:7331/?root=notes
+added: /Users/you/notes (notes)
+$ mdview ls
+● api    ~/work/api    (primary)
+● notes  ~/notes
+
+server:  http://mdview.localhost:7331/  (pid 40113)
+logs:    ~/.config/mdview/daemon.log
+```
+
+Folders stay open until you remove them with `mdview rm <name>`, across restarts
+and reboots. Up to 8 at a time — each one holds a live file watcher, so the
+limit is there to keep mdview from quietly watching your whole disk. Opening a
+file or subfolder inside a folder that's already open reuses it rather than
+adding a duplicate.
+
+The server keeps running until you `mdview stop` it, or you reboot. If you'd
+rather it stood down on its own, set `MDVIEW_IDLE_TIMEOUT` to a number of
+minutes and it will exit that long after the last browser tab disconnects; the
+next `mdview` starts it again.
+
+Its state lives in `~/.config/mdview/` (`daemon.json`, `workspace.json`,
+`daemon.log`) and nowhere else. `workspace.json` is also how the CLI talks to
+the server: `mdview <path>` writes the file and the server picks the change up,
+which is why there is no HTTP endpoint that can change what's being served.
+
+The URL is `http://mdview.localhost:7331/` — `*.localhost` always resolves to
+loopback (RFC 6761) with no setup, and the server still listens on `127.0.0.1`
+only. If your resolver doesn't answer the name, mdview falls back to printing
+`http://127.0.0.1:<port>/`. Setting `PORT` changes the default port, so mdview
+works as-is behind a local proxy like
+[portless](https://github.com/vercel-labs/portless) if you want the port gone
+entirely.
+
+`--palette` takes `classic`, `paper`, `nord`, `solarized`, or `high-contrast`.
+It wins over both `.mdview.json` and the global config, and never writes to
+either. There is also a `--vscode` flag, used by the VS Code extension to run
+mdview as a sidecar; it implies `--no-open` and prints a single JSON ready line
+instead of the human-readable output.
+
+`--port` and `--palette` both override a setting that belongs to a whole server,
+and the background one is shared with every other folder you have open — so each
+implies `--foreground`, giving you a server of your own. That also means every
+invocation that worked before still behaves exactly as it did; only the bare
+`mdview [path]` form returns the shell now.
+
+`--foreground` closes when you `Ctrl-C` or `kill` it. The background server is
+stopped with `mdview stop`. Set `MDVIEW_DEBUG=1` for full stack traces on
+unexpected errors.
 
 ## Keyboard shortcuts
 
@@ -186,7 +252,7 @@ Node 20+, TypeScript, Fastify 5, markdown-it 14, Shiki 1, gray-matter, chokidar
 ## Tests
 
 ```bash
-npm test            # vitest, server + client (289 tests)
+npm test            # vitest, server + client
 npm run typecheck   # both tsconfigs
 npm run build       # vite (client) + tsup (server CLI)
 ```