mdbrowse-cli 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# mdbrowse
+
+**Browse and preview markdown files in any directory.**
+
+[![npm version](https://img.shields.io/npm/v/mdbrowse)](https://www.npmjs.com/package/mdbrowse)
+[![license](https://img.shields.io/npm/l/mdbrowse)](LICENSE)
+
+Zero-install CLI that spins up a local web UI with a file tree, rendered markdown, live reload, and optional Cloudflare Tunnel for remote access.
+
+<!-- TODO: Add screenshot here -->
+<!-- ![mdbrowse screenshot](docs/screenshot.png) -->
+
+## Quick start
+
+```bash
+npx mdbrowse .           # serve current directory
+npx mdbrowse ./docs      # serve a specific folder
+npx mdbrowse . --tunnel  # expose via Cloudflare Tunnel
+```
+
+Opens in your browser automatically. On SSH/headless servers, grab the printed URL.
+
+## Features
+
+- 📁 **File tree sidebar** — browse all files in the directory
+- 📝 **Markdown rendering** — GFM tables, task lists, strikethrough, and more
+- 🎨 **Syntax highlighting** — VS Code-quality code blocks via Shiki
+- 🔢 **Math & diagrams** — LaTeX math (KaTeX) and Mermaid diagrams
+- 📋 **Frontmatter** — YAML frontmatter displayed as a clean table
+- 🔴 **Live reload** — auto-refreshes when files change on disk
+- ✏️ **Edit mode** — toggle to edit, Ctrl+S to save, tab indentation
+- 🔍 **Search** — filename + content search, Ctrl+K to open
+- 🌗 **Dark / light theme** — auto-detects system preference, with toggle
+- 🌐 **Cloudflare Tunnel** — instant public URL with `--tunnel`
+- 🔒 **Basic auth** — protect access with `--auth user:pass`
+- 🚫 **Read-only mode** — disable editing with `--read-only`
+
+## CLI flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `[directory]` | `.` | Directory to serve |
+| `-p, --port <number>` | `3000` | Port to listen on |
+| `--host <address>` | `localhost` | Host to bind to (use `0.0.0.0` for all interfaces) |
+| `--tunnel` | off | Expose via Cloudflare Tunnel (requires `cloudflared`) |
+| `--auth <user:pass>` | off | Require basic HTTP authentication |
+| `--read-only` | off | Disable file editing |
+| `--no-ignore` | off | Show all files (don't respect `.gitignore`) |
+
+## Use cases
+
+**Remote / headless servers** — Working on a cloud dev box or VPS? Run `npx mdbrowse . --tunnel` to get a public URL and view rendered markdown from any browser.
+
+**AI coding tools** — Using Claude Code, Codex, or similar tools that generate lots of markdown? Browse their output rendered, not raw.
+
+**Documentation browsing** — Point it at your `docs/` folder for a quick local docs site with search, live reload, and edit support.
+
+## Tech stack
+
+[Hono](https://hono.dev/) server, [unified](https://unifiedjs.com/)/remark markdown pipeline, [Shiki](https://shiki.style/) syntax highlighting, [KaTeX](https://katex.org/) math, [Mermaid](https://mermaid.js.org/) diagrams, [chokidar](https://github.com/paulmillr/chokidar) file watching, vanilla JS frontend — no build step.
+
+## License
+
+[MIT](LICENSE)

package/bin/mdnow.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { startServer } from '../src/server.js';
+
+const program = new Command();
+
+program
+  .name('mdnow')
+  .description('Browse and preview markdown files in any directory')
+  .version('0.1.0')
+  .argument('[directory]', 'Directory to serve', '.')
+  .option('-p, --port <number>', 'Port to listen on', '3000')
+  .option('--host <address>', 'Host to bind to', 'localhost')
+  .option('--no-ignore', 'Show all files (ignore .gitignore)')
+  .option('--auth <credentials>', 'Require basic auth (user:pass)')
+  .option('--read-only', 'Disable file editing')
+  .option('--tunnel', 'Expose via Cloudflare Tunnel (requires cloudflared)')
+  .action(async (directory, options) => {
+    const port = parseInt(options.port, 10);
+    const host = options.host;
+    const respectIgnore = options.ignore !== false;
+    const readOnly = !!options.readOnly;
+
+    let auth;
+    if (options.auth) {
+      if (!options.auth.includes(':')) {
+        console.error('Error: --auth must be in user:pass format');
+        process.exit(1);
+      }
+      const [user, ...rest] = options.auth.split(':');
+      auth = { username: user, password: rest.join(':') };
+    }
+
+    await startServer({
+      directory,
+      port,
+      host,
+      respectIgnore,
+      auth,
+      readOnly,
+    });
+
+    const url = `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`;
+    console.log(`\n  mdnow serving ${directory}`);
+    console.log(`  → ${url}\n`);
+
+    if (options.tunnel) {
+      const { startTunnel, registerCleanup } = await import('../src/tunnel.js');
+      try {
+        console.log('  Starting Cloudflare Tunnel...');
+        const { url: tunnelUrl, child } = await startTunnel(port);
+        registerCleanup(child);
+        console.log(`  → ${tunnelUrl}\n`);
+      } catch (err) {
+        console.error(`\n  ${err.message}\n`);
+        process.exit(1);
+      }
+    }
+
+    // Open browser if not in a headless/SSH environment
+    const isHeadless = !!(
+      process.env.SSH_CLIENT ||
+      process.env.SSH_TTY ||
+      process.env.SSH_CONNECTION
+    );
+
+    if (!isHeadless) {
+      const { exec } = await import('child_process');
+      const cmd =
+        process.platform === 'darwin'
+          ? 'open'
+          : process.platform === 'win32'
+            ? 'start'
+            : 'xdg-open';
+      exec(`${cmd} ${url}`);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mdbrowse-cli",
+  "version": "0.1.0",
+  "description": "CLI tool to browse and preview markdown files in any directory",
+  "type": "module",
+  "bin": {
+    "mdnow": "bin/mdnow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/"
+  ],
+  "keywords": [
+    "markdown",
+    "browser",
+    "preview",
+    "cli",
+    "file-browser",
+    "live-reload"
+  ],
+  "scripts": {
+    "test": "playwright test"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@hono/node-server": "^1.14.0",
+    "chokidar": "^4.0.0",
+    "commander": "^13.1.0",
+    "gray-matter": "^4.0.0",
+    "hono": "^4.7.0",
+    "ignore": "^7.0.0",
+    "rehype-katex": "^7.0.0",
+    "rehype-stringify": "^10.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-html": "^16.0.0",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "shiki": "^3.0.0",
+    "unified": "^11.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2"
+  }
+}