md-copilot-viewer 1.0.0

package/.env.template

@@ -0,0 +1,12 @@
+# Server port used by `npm run dev` / `npm start` (defaults to 3000)
+PORT=3000
+
+# true: include existing .md files at startup, false: only track newly created files after startup
+LOAD_EXISTING_MD=true
+
+# Comma-separated quoted path substrings to exclude from results
+# Example: "checkpoints/index.md","tmp/","node_modules/"
+EXCLUDE_PATTERN='"checkpoints/index.md"'
+
+# Maximum number of most recently updated files sent to the frontend
+FILE_MAX_LIMIT=200

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,62 @@
+# Markdown File Viewer for Copilot
+Simple markdown file viewer for Copilot/session notes, with DOCX export.
+
+## Features
+
+- Realtime monitoring of `.md` files, so new and updated notes appear automatically.
+- Live markdown preview with a quick file list for fast context switching.
+- Optional DOCX export for sharing notes outside the app.
+
+## How it works
+
+1. A Node watcher tracks markdown file changes (create/update) in realtime.
+2. The backend serves a capped, recent file list plus rendered markdown content.
+3. The web UI refreshes the list/preview automatically and supports DOCX export.
+
+## Screenshots
+
+![Screenshot 1 - file list and markdown preview](web/screenshots/screenshot-1.png)
+![Screenshot 2 - rendered markdown and export](web/screenshots/screenshot-2.png)
+
+## Run
+
+```bash
+npm install
+cp .env.template .env
+npm run dev
+```
+
+`npm run dev` uses `PORT` from `.env` (default `3000`), so open:
+- `http://localhost:3000` (default), or
+- `http://localhost:<your PORT value>`
+
+## `.env` config
+
+`.env.template` includes:
+
+```env
+PORT=3000
+LOAD_EXISTING_MD=true
+EXCLUDE_PATTERN='"checkpoints/index.md"'
+FILE_MAX_LIMIT=200
+```
+
+- `PORT`  
+  Port used by `npm run dev` and `npm start` (default `3000`).
+- `LOAD_EXISTING_MD`  
+  - `true`: load markdown files that already exist when the app starts.  
+  - `false`: only watch new markdown files created after startup.
+- `EXCLUDE_PATTERN`  
+  Comma-separated path substrings to ignore.  
+  Example: `"checkpoints/index.md","tmp/","node_modules/"`
+- `FILE_MAX_LIMIT`  
+  Maximum number of most recently updated markdown files returned to the frontend (default `200`).
+
+## API endpoints
+
+- `GET /api/files`  
+  Returns recent markdown files (max `FILE_MAX_LIMIT`) with `id`, display `path`, and `mtimeMs`.
+- `GET /api/files/:id`  
+  Returns one file as `{ path, markdown, html }`.
+- `GET /api/files/:id/docx`  
+  Downloads the selected markdown file as `.docx`.

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./index.js";

package/dist/index.js

@@ -0,0 +1,93 @@
+import express from "express";
+import dotenv from "dotenv";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { markdownToDocx, renderMarkdown } from "./markdown.js";
+import { defaultRoots, MarkdownIndex } from "./watcher.js";
+dotenv.config();
+function parseExcludePatterns(rawValue) {
+    if (!rawValue) {
+        return [];
+    }
+    const matches = rawValue.matchAll(/"([^"]+)"/g);
+    return [...matches].map((match) => match[1]).filter((item) => item.length > 0);
+}
+function parseFileMaxLimit(rawValue) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        return 200;
+    }
+    return Math.floor(parsed);
+}
+function toDisplayPath(filePath) {
+    const homePath = os.homedir();
+    if (filePath === homePath) {
+        return "~";
+    }
+    if (filePath.startsWith(`${homePath}/`)) {
+        return `~/${filePath.slice(homePath.length + 1)}`;
+    }
+    return filePath;
+}
+const app = express();
+const port = Number(process.env.PORT || 3000);
+const loadExistingMd = process.env.LOAD_EXISTING_MD !== "false";
+const excludePatterns = parseExcludePatterns(process.env.EXCLUDE_PATTERN);
+const fileMaxLimit = parseFileMaxLimit(process.env.FILE_MAX_LIMIT);
+const cwd = process.cwd();
+const roots = defaultRoots(cwd);
+const index = new MarkdownIndex(roots, loadExistingMd, excludePatterns);
+const currentFile = fileURLToPath(import.meta.url);
+const webDir = path.resolve(path.dirname(currentFile), "../web");
+app.use(express.static(webDir));
+app.get("/api/files", (_req, res) => {
+    res.json(index.list().slice(0, fileMaxLimit).map((entry) => ({
+        ...entry,
+        path: toDisplayPath(entry.path)
+    })));
+});
+app.get("/api/files/:id", async (req, res) => {
+    const filePath = index.resolve(req.params.id);
+    if (!filePath) {
+        res.status(404).json({ error: "File not found" });
+        return;
+    }
+    try {
+        const markdown = await fs.readFile(filePath, "utf8");
+        res.json({ path: toDisplayPath(filePath), markdown, html: renderMarkdown(markdown) });
+    }
+    catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+app.get("/api/files/:id/docx", async (req, res) => {
+    const filePath = index.resolve(req.params.id);
+    if (!filePath) {
+        res.status(404).json({ error: "File not found" });
+        return;
+    }
+    try {
+        const markdown = await fs.readFile(filePath, "utf8");
+        const buffer = await markdownToDocx(markdown);
+        const fileName = `${path.basename(filePath, ".md")}.docx`;
+        res.setHeader("Content-Type", "application/vnd.openxmlformats-officedocument.wordprocessingml.document");
+        res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
+        res.send(buffer);
+    }
+    catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+async function start() {
+    await index.start();
+    app.listen(port, () => {
+        console.log(`Server running on http://localhost:${port}`);
+        console.log(`LOAD_EXISTING_MD=${String(loadExistingMd)}`);
+        console.log(`EXCLUDE_PATTERN=${excludePatterns.join(",") || "(none)"}`);
+        console.log(`FILE_MAX_LIMIT=${String(fileMaxLimit)}`);
+        console.log(`Watching roots:\n- ${roots.join("\n- ")}`);
+    });
+}
+void start();

package/dist/markdown.js

@@ -0,0 +1,67 @@
+import MarkdownIt from "markdown-it";
+import texmath from "markdown-it-texmath";
+import katex from "katex";
+import HTMLtoDOCX from "html-to-docx";
+const md = new MarkdownIt({ html: true, linkify: true, breaks: true })
+    .use(texmath, { engine: katex, delimiters: "dollars" });
+const defaultFence = md.renderer.rules.fence;
+md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    const info = (token.info || "").trim();
+    if (info === "mermaid") {
+        return `<pre class="mermaid">${md.utils.escapeHtml(token.content)}</pre>`;
+    }
+    if (defaultFence) {
+        return defaultFence(tokens, idx, options, env, self);
+    }
+    return self.renderToken(tokens, idx, options);
+};
+function extractTitle(markdown) {
+    const match = markdown.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : "Document";
+}
+function generateStyledHtml(htmlContent, title) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="color-scheme" content="light">
+  <title>${title}</title>
+  <style>
+    :root { color-scheme: light; }
+    body { font-family: 'Times New Roman', Times, serif; font-size: 12pt; line-height: 1.5; color: #333; background: #fff; }
+    h1 { font-size: 24pt; margin: 24pt 0 12pt; color: #2c3e50; }
+    h2 { font-size: 18pt; margin: 18pt 0 10pt; color: #34495e; }
+    h3 { font-size: 14pt; margin: 14pt 0 8pt; }
+    p { margin: 0 0 10pt; text-align: justify; }
+    ul, ol { margin: 0 0 10pt; padding-left: 20pt; }
+    blockquote { margin: 10pt 0; padding-left: 15pt; border-left: 3px solid #3498db; color: #666; font-style: italic; }
+    code { font-family: 'Courier New', Courier, monospace; font-size: 10pt; background-color: #f4f4f4; padding: 2pt 4pt; }
+    pre { font-family: 'Courier New', Courier, monospace; font-size: 10pt; background-color: #f4f4f4; padding: 10pt; margin: 10pt 0; white-space: pre-wrap; word-wrap: break-word; }
+    table { border-collapse: collapse; width: 100%; margin: 10pt 0; }
+    th, td { border: 1px solid #ddd; padding: 8pt; text-align: left; }
+    th { background-color: #f5f5f5; }
+    a { color: #3498db; text-decoration: underline; }
+    img { max-width: 100%; height: auto; }
+  </style>
+</head>
+<body>
+${htmlContent}
+</body>
+</html>`;
+}
+export function renderMarkdown(markdown) {
+    return md.render(markdown);
+}
+export async function markdownToDocx(markdown) {
+    const title = extractTitle(markdown);
+    const htmlContent = md.render(markdown);
+    const fullHtml = generateStyledHtml(htmlContent, title);
+    return HTMLtoDOCX(fullHtml, null, {
+        title,
+        subject: "Converted from Markdown",
+        creator: "Marky-compatible exporter",
+        font: "Times New Roman",
+        fontSize: 24
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/watcher.js

@@ -0,0 +1,105 @@
+import chokidar from "chokidar";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function toId(filePath) {
+    return Buffer.from(filePath, "utf8").toString("base64url");
+}
+function isMarkdown(filePath) {
+    return filePath.toLowerCase().endsWith(".md");
+}
+export class MarkdownIndex {
+    roots;
+    loadExistingOnStart;
+    excludePatterns;
+    byPath = new Map();
+    byId = new Map();
+    watcher;
+    constructor(roots, loadExistingOnStart, excludePatterns) {
+        this.roots = roots;
+        this.loadExistingOnStart = loadExistingOnStart;
+        this.excludePatterns = excludePatterns;
+    }
+    async start() {
+        if (this.loadExistingOnStart) {
+            await this.seedExisting();
+        }
+        this.watcher = chokidar.watch(this.roots, {
+            ignored: (p) => p.includes("/node_modules/") || p.includes("/.git/"),
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 100 }
+        });
+        this.watcher.on("add", (filePath) => void this.upsert(filePath));
+        this.watcher.on("change", (filePath) => void this.upsert(filePath));
+        this.watcher.on("unlink", (filePath) => this.remove(filePath));
+    }
+    async seedExisting() {
+        await Promise.all(this.roots.map((root) => this.walk(root)));
+    }
+    async walk(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        await Promise.all(entries.map(async (entry) => {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === ".git") {
+                    return;
+                }
+                await this.walk(fullPath);
+                return;
+            }
+            if (entry.isFile() && isMarkdown(fullPath)) {
+                await this.upsert(fullPath);
+            }
+        }));
+    }
+    async upsert(filePath) {
+        if (!isMarkdown(filePath)) {
+            return;
+        }
+        if (this.isExcluded(filePath)) {
+            this.remove(filePath);
+            return;
+        }
+        try {
+            const stat = await fs.stat(filePath);
+            if (!stat.isFile()) {
+                return;
+            }
+            const id = toId(filePath);
+            const entry = { id, path: filePath, mtimeMs: stat.mtimeMs };
+            this.byPath.set(filePath, entry);
+            this.byId.set(id, filePath);
+        }
+        catch {
+            this.remove(filePath);
+        }
+    }
+    remove(filePath) {
+        const existing = this.byPath.get(filePath);
+        if (!existing) {
+            return;
+        }
+        this.byPath.delete(filePath);
+        this.byId.delete(existing.id);
+    }
+    list() {
+        return [...this.byPath.values()].sort((a, b) => b.mtimeMs - a.mtimeMs);
+    }
+    resolve(id) {
+        return this.byId.get(id);
+    }
+    isExcluded(filePath) {
+        const normalizedPath = filePath.replaceAll("\\", "/");
+        return this.excludePatterns.some((pattern) => normalizedPath.includes(pattern));
+    }
+}
+export function defaultRoots(cwd) {
+    return [cwd, path.join(os.homedir(), ".copilot")];
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "md-copilot-viewer",
+  "version": "1.0.0",
+  "description": "Watch markdown files and view them in a browser with DOCX export",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "md-copilot-viewer": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "web",
+    ".env.template",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "html-to-docx": "^1.8.0",
+    "katex": "^0.16.25",
+    "markdown-it": "^14.1.0",
+    "markdown-it-texmath": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/web/app.js

@@ -0,0 +1,109 @@
+const fileListEl = document.getElementById("file-list");
+const searchInputEl = document.getElementById("file-search");
+const previewEl = document.getElementById("preview");
+const currentFileEl = document.getElementById("current-file");
+const downloadBtn = document.getElementById("download-docx");
+
+let files = [];
+let selectedId = null;
+let searchQuery = "";
+let initialized = false;
+const knownIds = new Set();
+const unreadIds = new Set();
+
+function renderList() {
+  fileListEl.innerHTML = "";
+  const query = searchQuery.toLowerCase();
+  const visibleFiles = query ? files.filter((file) => file.path.toLowerCase().includes(query)) : files;
+  for (const file of visibleFiles) {
+    const li = document.createElement("li");
+    li.className = selectedId === file.id ? "active" : "";
+    const label = document.createElement("span");
+    label.className = "file-item-label";
+    label.textContent = `${file.path} (${new Date(file.mtimeMs).toLocaleString()})`;
+    li.appendChild(label);
+    if (unreadIds.has(file.id)) {
+      const dot = document.createElement("span");
+      dot.className = "unread-dot";
+      dot.setAttribute("aria-label", "New file");
+      li.appendChild(dot);
+    }
+    li.addEventListener("click", () => selectFile(file.id));
+    fileListEl.appendChild(li);
+  }
+}
+
+async function refreshFiles() {
+  const res = await fetch("/api/files");
+  files = await res.json();
+  const currentIds = new Set(files.map((f) => f.id));
+  if (!initialized) {
+    for (const file of files) {
+      knownIds.add(file.id);
+    }
+    initialized = true;
+  } else {
+    for (const file of files) {
+      if (!knownIds.has(file.id)) {
+        unreadIds.add(file.id);
+        knownIds.add(file.id);
+      }
+    }
+  }
+  for (const id of [...unreadIds]) {
+    if (!currentIds.has(id)) {
+      unreadIds.delete(id);
+    }
+  }
+  if (!selectedId && files.length > 0) {
+    selectedId = files[0].id;
+  }
+  if (selectedId && !files.some((f) => f.id === selectedId)) {
+    selectedId = files[0]?.id ?? null;
+  }
+  renderList();
+  if (selectedId) {
+    await loadPreview(selectedId);
+  } else {
+    previewEl.innerHTML = "<p>No markdown files found yet.</p>";
+    currentFileEl.textContent = "";
+    downloadBtn.disabled = true;
+  }
+}
+
+async function loadPreview(id) {
+  const res = await fetch(`/api/files/${encodeURIComponent(id)}`);
+  if (!res.ok) {
+    previewEl.textContent = "Failed to load file.";
+    return;
+  }
+  const data = await res.json();
+  selectedId = id;
+  unreadIds.delete(id);
+  renderList();
+  previewEl.innerHTML = data.html;
+  currentFileEl.textContent = data.path;
+  downloadBtn.disabled = false;
+  const mermaid = window.__mermaid;
+  if (mermaid) {
+    mermaid.initialize({ startOnLoad: false });
+    await mermaid.run({ nodes: previewEl.querySelectorAll(".mermaid") });
+  }
+}
+
+async function selectFile(id) {
+  await loadPreview(id);
+}
+
+downloadBtn.addEventListener("click", () => {
+  if (!selectedId) return;
+  window.location.href = `/api/files/${encodeURIComponent(selectedId)}/docx`;
+});
+
+searchInputEl.addEventListener("input", (event) => {
+  searchQuery = event.target.value;
+  renderList();
+});
+
+refreshFiles();
+setInterval(refreshFiles, 2000);

package/web/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Markdown Copilot Viewer</title>
+    <link rel="stylesheet" href="/styles.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css" />
+  </head>
+  <body>
+    <div class="app">
+      <aside class="sidebar">
+        <h2>Markdown files</h2>
+        <input id="file-search" type="text" placeholder="Search files..." aria-label="Search markdown files" />
+        <ul id="file-list"></ul>
+      </aside>
+      <main class="content">
+        <div class="toolbar">
+          <button id="download-docx" disabled>Download as DOCX</button>
+          <span id="current-file"></span>
+        </div>
+        <article id="preview"></article>
+      </main>
+    </div>
+    <script type="module" src="/app.js"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      window.__mermaid = mermaid;
+    </script>
+  </body>
+</html>

package/web/styles.css

@@ -0,0 +1,18 @@
+* { box-sizing: border-box; }
+body { margin: 0; font-family: Arial, sans-serif; color: #1a1a1a; background: #fff; }
+.app { display: grid; grid-template-columns: 320px 1fr; height: 100vh; }
+.sidebar { border-right: 1px solid #ddd; padding: 12px; overflow: auto; }
+.sidebar h2 { margin: 0 0 12px; font-size: 18px; }
+#file-search { width: 100%; margin: 0 0 10px; padding: 8px; border: 1px solid #ccc; border-radius: 6px; }
+#file-list { list-style: none; padding: 0; margin: 0; }
+#file-list li { display: flex; align-items: center; gap: 8px; padding: 8px; border-radius: 6px; cursor: pointer; margin-bottom: 4px; }
+#file-list li:hover, #file-list li.active { background: #eef4ff; }
+.file-item-label { overflow-wrap: anywhere; flex: 1; }
+.unread-dot { width: 9px; height: 9px; border-radius: 50%; background: #8be28b; flex: 0 0 auto; }
+.content { display: flex; flex-direction: column; min-width: 0; }
+.toolbar { display: flex; align-items: center; gap: 12px; padding: 12px; border-bottom: 1px solid #ddd; }
+#preview { padding: 20px; overflow: auto; }
+#preview pre { background: #f5f5f5; padding: 10px; border-radius: 6px; overflow: auto; }
+#preview table { border-collapse: collapse; width: 100%; }
+#preview th, #preview td { border: 1px solid #ccc; padding: 8px; }
+#preview .mermaid { background: #fff; }