repoview 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for helping improve `repoview`.
+
+## Setup
+
+```bash
+npm install
+```
+
+## Run
+
+```bash
+npm start -- --repo /path/to/repo --port 3000
+```
+
+## Lint
+
+```bash
+npm run lint
+```
+
+## What to work on
+
+High-impact contributions:
+- GitHub-parity improvements for Markdown rendering
+- Performance on large repos (pagination, caching, faster scanning)
+- UI polish (especially mobile)
+- Security hardening (path handling, sanitization rules)
+
+Implementation notes: `DEVELOPMENT.md`.
+

package/DEVELOPMENT.md

@@ -0,0 +1,69 @@
+# Development
+
+This doc collects the “how it works” details so `README.md` can stay product-focused.
+
+## Project layout
+
+- `src/server.js`: Express server + routes (`/tree`, `/blob`, `/raw`, `/events`)
+- `src/markdown.js`: Markdown rendering + link/image rewriting + sanitization
+- `src/linkcheck.js`: broken-link scanner (Markdown → rendered HTML → internal link validation)
+- `src/gitignore.js`: `.gitignore` matcher (used for hiding + scanner noise reduction)
+- `src/views.js`: HTML templates (mobile-first top bar + GitHub-style Markdown shell)
+- `public/`: CSS + client JS (live reload, KaTeX render, Mermaid render, query preservation)
+
+## Running locally
+
+```bash
+npm install
+npm start -- --repo /path/to/repo --port 3000
+```
+
+Useful flags:
+- `--watch` / `--no-watch` (watch is on by default)
+- `--host 0.0.0.0` to access from other devices on the network
+
+## Routes
+
+- `GET /tree/<path>`: directory listing (applies `.gitignore` by default; `?ignored=1` shows ignored)
+- `GET /blob/<path>`: file view (Markdown rendered; non-Markdown shown as highlighted text)
+- `GET /raw/<path>`: raw bytes (used for images and downloads)
+- `GET /events`: Server-Sent Events stream for live reload
+- `GET /broken-links`: HTML report for broken internal links (Markdown docs)
+- `GET /broken-links.json`: report state + raw results
+
+## Link rewriting rules
+
+`src/markdown.js` rewrites relative Markdown links so they stay inside the repo UI:
+
+- Links → `/blob/<path>` (or `/tree/<path>` when the link ends with `/`)
+- Images → `/raw/<path>`
+- Same rewriting is applied to HTML inside Markdown (`<a href>`, `<img src>`) after sanitization.
+- Paths that would escape the repo root (leading `../`) are clamped to the repo root (GitHub-like).
+- Already-internal links (`/blob/…`, `/tree/…`, `/raw/…`, `/static/…`) are not rewritten again.
+
+## Markdown “GitHub-like” features
+
+The renderer is not `cmark-gfm`, but aims to be “close enough” for typical README/docs:
+
+- Tables, strikethrough, autolinks
+- Task lists (`- [x]`)
+- Footnotes
+- Emoji shortcodes (`:smile:`)
+- Callouts (`> [!NOTE]`, `> [!TIP]`, …)
+- Math (KaTeX auto-render on the client)
+- Mermaid fenced blocks
+
+## Broken link scanning
+
+The scanner renders Markdown, extracts internal `href/src` links, and validates that the referenced repo paths exist.
+
+Notes:
+- `.gitignore`d files are hidden by default and are also skipped by the scanner (to reduce noise).
+- The scanner runs at startup and re-runs on filesystem changes when watch is enabled.
+
+## Lint
+
+```bash
+npm run lint
+```
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 repoview contributors
+
+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,75 @@
+# repoview
+
+GitHub-like repo browsing — without GitHub.
+
+When platforms change pricing/terms (even for “bring-your-own-runner” CI), it’s a reminder that Git hosting can turn into a dependency and a risk. `repoview` keeps the day-to-day “GitHub UI” experience local: browse, read docs, and share a repo without pushing it anywhere.
+
+Not affiliated with GitHub.
+
+## Features
+
+- GitHub-like browsing for local repos (tree / file / raw views)
+- GitHub-style Markdown rendering (README-friendly; close-to-GitHub)
+- Live reload when files change (SSE with polling fallback)
+- Broken internal link discovery for docs (`/broken-links`)
+- Respects `.gitignore` by default (toggleable)
+
+## Quick start (from source)
+
+```bash
+npm install
+npm start -- --repo /path/to/your/repo --port 3000
+```
+
+Then open `http://localhost:3000`.
+
+## Quick start (npx)
+
+After publishing to npm:
+
+```bash
+npx repoview --repo /path/to/your/repo --port 3000
+```
+
+## Why
+
+- Keep GitHub as a remote, not your developer portal.
+- Share private repos/docs on a LAN without pushing or mirroring.
+- Work offline / in restricted networks with the same browsing UX.
+
+## Usage
+
+```bash
+npm start -- --repo /path/to/repo [--host 127.0.0.1] [--port 3000] [--no-watch]
+```
+
+Common flags:
+- `--repo`: repo root
+- `--host`, `--port`: bind address/port
+- `--no-watch`: disable live reload + auto re-scan
+
+## Share on LAN (optional)
+
+Bind to all interfaces, then open the host URL from another device:
+
+```bash
+npm start -- --repo /path/to/repo --host 0.0.0.0 --port 8890
+```
+
+## UI toggles
+
+- `?ignored=1` shows files ignored by the repo’s `.gitignore` (default: hidden)
+- `?watch=0` disables browser auto-refresh for that tab
+
+## Development
+
+- Implementation details: [`DEVELOPMENT.md`](DEVELOPMENT.md)
+- CLI usage: `npm start -- --help`
+
+## Contributing
+
+- Contributing guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "repoview",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "GitHub-like repo browsing for local Git repositories (Markdown, live reload, broken link scanner).",
+  "license": "MIT",
+  "author": "Hang Yin <hangyin@phala.com>",
+  "bin": {
+    "repoview": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "public/",
+    "README.md",
+    "LICENSE",
+    "DEVELOPMENT.md",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "git",
+    "repository",
+    "viewer",
+    "markdown",
+    "github",
+    "docs",
+    "live-reload"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "dev": "node src/cli.js --watch",
+    "lint": "node -c src/cli.js && node -c src/server.js && node -c src/markdown.js && node -c src/views.js"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "express": "^4.21.2",
+    "github-markdown-css": "^5.8.1",
+    "github-slugger": "^2.0.0",
+    "highlight.js": "^11.11.1",
+    "ignore": "^7.0.5",
+    "katex": "^0.16.22",
+    "markdown-it": "^14.1.0",
+    "markdown-it-emoji": "^3.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1",
+    "mermaid": "^11.12.0",
+    "mime-types": "^2.1.35",
+    "sanitize-html": "^2.17.0"
+  }
+}

package/public/app.css

@@ -0,0 +1,443 @@
+:root {
+  color-scheme: light;
+  --bg: #ffffff;
+  --panel: #ffffff;
+  --text: #24292f;
+  --muted: #57606a;
+  --border: #d0d7de;
+  --subtleBg: #f6f8fa;
+  --btn: #f6f8fa;
+  --btnHover: #f3f4f6;
+  --accent: #0969da;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial,
+    "Apple Color Emoji", "Segoe UI Emoji";
+  background: var(--bg);
+  color: var(--text);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.container {
+  padding: 16px;
+  max-width: 980px;
+  margin: 0 auto;
+}
+
+.topbar {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: rgba(255, 255, 255, 0.92);
+  backdrop-filter: saturate(180%) blur(8px);
+  border-bottom: 1px solid var(--border);
+}
+
+.topbar-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px 12px 8px;
+}
+
+.brand {
+  font-weight: 700;
+  letter-spacing: 0.2px;
+  max-width: 50vw;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.meta {
+  margin-left: auto;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.meta-actions {
+  display: inline-flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.meta-menu {
+  display: none;
+  position: relative;
+}
+
+.meta-menu summary {
+  list-style: none;
+  cursor: pointer;
+}
+
+.meta-menu summary::-webkit-details-marker {
+  display: none;
+}
+
+.menu-panel {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 8px);
+  min-width: 210px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--panel);
+  padding: 6px;
+  box-shadow: 0 8px 24px rgba(31, 35, 40, 0.12);
+}
+
+.menu-item {
+  display: block;
+  padding: 8px 10px;
+  border-radius: 6px;
+  color: var(--text);
+  font-size: 14px;
+}
+
+.menu-item:hover {
+  background: var(--subtleBg);
+}
+
+.pill {
+  padding: 3px 8px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: #fff;
+}
+
+.mono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
+}
+
+.breadcrumbs {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  overflow-x: auto;
+  padding: 0 12px 12px;
+  scrollbar-width: none;
+}
+
+.breadcrumbs::-webkit-scrollbar {
+  display: none;
+}
+
+.crumb {
+  color: var(--muted);
+  font-size: 13px;
+  white-space: nowrap;
+}
+
+.crumb:hover {
+  color: var(--text);
+}
+
+.crumb-sep {
+  color: rgba(31, 35, 40, 0.28);
+}
+
+.panel {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--panel);
+  overflow: hidden;
+}
+
+.container > .panel + .panel {
+  margin-top: 12px;
+}
+
+.panel-title {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px;
+  border-bottom: 1px solid var(--border);
+  background: var(--subtleBg);
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.filename {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.spacer {
+  flex: 1;
+}
+
+.btn {
+  font-weight: 600;
+  font-size: 14px;
+  padding: 5px 10px;
+  border-radius: 6px;
+  border: 1px solid var(--border);
+  background: var(--btn);
+}
+
+.btn:hover {
+  background: var(--btnHover);
+}
+
+.link {
+  color: var(--accent);
+}
+.link:hover {
+  text-decoration: underline;
+}
+
+.table-wrap {
+  overflow-x: auto;
+}
+
+.file-table {
+  width: 100%;
+  border-collapse: collapse;
+  min-width: 520px;
+}
+
+.file-table th,
+.file-table td {
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border);
+  font-size: 14px;
+}
+
+.file-table th {
+  text-align: left;
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.file-table.linkcheck th,
+.file-table.linkcheck td {
+  font-size: 13px;
+}
+
+.file-table td.size,
+.file-table th.size {
+  text-align: right;
+  width: 90px;
+}
+
+.file-table td.mtime {
+  width: 160px;
+  color: var(--muted);
+  font-size: 13px;
+}
+.file-table th.mtime {
+  width: 160px;
+}
+
+.file-table tr:hover td {
+  background: #f6f8fa;
+}
+
+.item {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.item::before {
+  content: "";
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  opacity: 0.85;
+  background: currentColor;
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+  -webkit-mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+}
+
+.item.dir::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M1.75 3A1.75 1.75 0 0 0 0 4.75v6.5C0 12.216.784 13 1.75 13h12.5c.966 0 1.75-.784 1.75-1.75v-5.5A1.75 1.75 0 0 0 14.25 4H7.5a.75.75 0 0 1-.53-.22L5.72 2.53A1.75 1.75 0 0 0 4.48 2H1.75Z'/%3E%3C/svg%3E");
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M1.75 3A1.75 1.75 0 0 0 0 4.75v6.5C0 12.216.784 13 1.75 13h12.5c.966 0 1.75-.784 1.75-1.75v-5.5A1.75 1.75 0 0 0 14.25 4H7.5a.75.75 0 0 1-.53-.22L5.72 2.53A1.75 1.75 0 0 0 4.48 2H1.75Z'/%3E%3C/svg%3E");
+}
+
+.item.file::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M4 1.75C4 .784 4.784 0 5.75 0h3.982c.464 0 .91.184 1.238.513l2.517 2.517c.329.328.513.774.513 1.238V14.25A1.75 1.75 0 0 1 12.25 16h-6.5A1.75 1.75 0 0 1 4 14.25V1.75Zm5.75-.25H5.75a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h6.5a.25.25 0 0 0 .25-.25V4.5H10a.75.75 0 0 1-.75-.75V1.5Z'/%3E%3C/svg%3E");
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M4 1.75C4 .784 4.784 0 5.75 0h3.982c.464 0 .91.184 1.238.513l2.517 2.517c.329.328.513.774.513 1.238V14.25A1.75 1.75 0 0 1 12.25 16h-6.5A1.75 1.75 0 0 1 4 14.25V1.75Zm5.75-.25H5.75a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h6.5a.25.25 0 0 0 .25-.25V4.5H10a.75.75 0 0 1-.75-.75V1.5Z'/%3E%3C/svg%3E");
+}
+
+.empty {
+  padding: 18px 12px;
+  color: var(--muted);
+  text-align: center;
+}
+
+.markdown-wrap {
+  padding: 16px;
+}
+
+.code-wrap {
+  padding: 0;
+}
+
+.code-wrap pre.hljs {
+  margin: 0;
+  padding: 16px;
+  overflow: auto;
+  background: #f6f8fa;
+}
+
+.note {
+  padding: 12px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: #f6f8fa;
+}
+
+.error {
+  padding: 12px;
+  color: #cf222e;
+}
+
+.markdown-body .markdown-alert {
+  margin: 16px 0;
+  padding: 12px 14px;
+  border: 1px solid var(--border);
+  border-left-width: 4px;
+  border-radius: 6px;
+  background: #f6f8fa;
+}
+
+.markdown-body .markdown-alert-title {
+  margin: 0 0 6px;
+  font-weight: 650;
+}
+
+.markdown-body .markdown-alert > :last-child {
+  margin-bottom: 0;
+}
+
+.markdown-body .markdown-alert-note {
+  border-left-color: #0969da;
+}
+.markdown-body .markdown-alert-tip {
+  border-left-color: #1a7f37;
+}
+.markdown-body .markdown-alert-important {
+  border-left-color: #8250df;
+}
+.markdown-body .markdown-alert-warning {
+  border-left-color: #9a6700;
+}
+.markdown-body .markdown-alert-caution {
+  border-left-color: #cf222e;
+}
+
+.markdown-body pre.mermaid {
+  padding: 12px;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: #f6f8fa;
+  overflow: auto;
+}
+
+.markdown-body h1,
+.markdown-body h2,
+.markdown-body h3,
+.markdown-body h4,
+.markdown-body h5,
+.markdown-body h6 {
+  position: relative;
+}
+
+.markdown-body .anchor {
+  position: absolute;
+  left: -22px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 18px;
+  height: 18px;
+  color: var(--muted);
+  visibility: hidden;
+}
+
+.markdown-body .anchor::before {
+  content: "";
+  display: inline-block;
+  width: 18px;
+  height: 18px;
+  background: currentColor;
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+  -webkit-mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M7.775 3.275a.75.75 0 0 1 0 1.06L6.06 6.05a2.5 2.5 0 0 0 3.536 3.536l1.715-1.715a.75.75 0 1 1 1.06 1.06l-1.715 1.716A4 4 0 0 1 5 4.99l1.715-1.716a.75.75 0 0 1 1.06 0Zm.45 9.45a.75.75 0 0 1 0-1.06l1.715-1.715A2.5 2.5 0 0 0 6.404 6.404L4.69 8.12a.75.75 0 1 1-1.06-1.06l1.715-1.716A4 4 0 1 1 11 11.01l-1.715 1.716a.75.75 0 0 1-1.06 0Z'/%3E%3C/svg%3E");
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M7.775 3.275a.75.75 0 0 1 0 1.06L6.06 6.05a2.5 2.5 0 0 0 3.536 3.536l1.715-1.715a.75.75 0 1 1 1.06 1.06l-1.715 1.716A4 4 0 0 1 5 4.99l1.715-1.716a.75.75 0 0 1 1.06 0Zm.45 9.45a.75.75 0 0 1 0-1.06l1.715-1.715A2.5 2.5 0 0 0 6.404 6.404L4.69 8.12a.75.75 0 1 1-1.06-1.06l1.715-1.716A4 4 0 1 1 11 11.01l-1.715 1.716a.75.75 0 0 1-1.06 0Z'/%3E%3C/svg%3E");
+}
+
+.markdown-body h1:hover > .anchor,
+.markdown-body h2:hover > .anchor,
+.markdown-body h3:hover > .anchor,
+.markdown-body h4:hover > .anchor,
+.markdown-body h5:hover > .anchor,
+.markdown-body h6:hover > .anchor {
+  visibility: visible;
+}
+
+@media (max-width: 560px) {
+  .markdown-body .anchor {
+    display: none;
+  }
+}
+
+@media (min-width: 720px) {
+  .container {
+    padding: 24px;
+  }
+  .topbar-row {
+    padding-left: 20px;
+    padding-right: 20px;
+  }
+  .breadcrumbs {
+    padding-left: 20px;
+    padding-right: 20px;
+  }
+}
+
+@media (max-width: 560px) {
+  .file-table {
+    min-width: 0;
+  }
+  .file-table th.mtime,
+  .file-table td.mtime,
+  .file-table th.size,
+  .file-table td.size {
+    display: none;
+  }
+
+  .meta-commit,
+  .meta-actions {
+    display: none;
+  }
+  .meta-menu {
+    display: inline-block;
+  }
+}