@astlw/peekmd 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# PeekMD
+
+A CLI tool that renders Markdown files in the browser and live-reloads on every file save.
+
+## Install
+
+```bash
+npm install -g peekmd
+```
+
+Requires Node.js 18+.
+
+## CLI Commands
+
+```bash
+# Server
+peekmd start                        # start server (daemon)
+peekmd stop                         # stop server
+peekmd status                       # check server status
+PORT=3000 peekmd start              # custom port (default: 4000)
+
+# Folder management
+peekmd link <dir> [dir2] ...        # persist folders to config
+peekmd unlink <dir> [dir2] ...      # remove folders from config
+peekmd list                         # show linked folders
+
+# Ignore patterns (glob syntax)
+peekmd ignore <pattern> ...         # ignore folders/files by glob pattern
+peekmd unignore <pattern> ...       # remove an ignore pattern
+peekmd ignored                      # show all active ignore patterns
+
+# Structured Output - making it easy to integrate with scripts or other tools.
+peekmd list --json                  # linked folders as JSON
+peekmd ignored --json               # ignore patterns as JSON
+peekmd status --json                # server status as JSON
+peekmd search <query>               # search files and content (JSON)
+peekmd files                        # list all markdown files (JSON)
+
+peekmd --help                       # print help
+```
+
+### Ignore Patterns
+
+Ignore patterns let you exclude folders or files from the file tree, search,
+and live-reload. Patterns are stored in `~/.peekmd.json` and apply globally.
+All patterns use **glob syntax** (picomatch).
+
+**Examples:**
+
+```bash
+peekmd ignore "**/node_modules/**"    # ignores all node_modules folders
+peekmd ignore "**/dist/**" "**/build/**"  # ignore multiple patterns
+peekmd ignore "**/*.draft.md"         # ignores all .draft.md files
+peekmd ignore "docs/private/**"       # ignores everything under docs/private
+peekmd ignore "*.tmp"                 # ignores .tmp files at any depth
+```
+
+**Default patterns** (applied automatically on first use):
+
+- `**/node_modules/**`
+- `**/.git/**`
+- `**/dist/**`
+- `**/build/**`
+- `**/.next/**`
+- `**/__pycache__/**`
+
+## Features
+
+| Feature                      |                                                                                                                      Summary | Why it matters                                                      |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------- |
+| Live reload                  |                                Real-time file events over WebSocket; open file preview refreshes on `add`/`change`/`unlink`. | Instant feedback while editing files.                               |
+| Folder groups (multi-folder) | Sidebar shows each linked folder as a separate group; when folder basenames collide a compact path is shown to disambiguate. | Keep multiple projects side-by-side without confusion.              |
+| File tree                    |                        Per-folder collapsible file tree with relative paths; click a file to render Markdown in the preview. | Fast navigation and focused previews.                               |
+| Ignore patterns (glob)       |                                                         Glob-only patterns (picomatch) applied to watcher, search, and tree. | Simple, consistent filtering across the app. Quote globs in shells. |
+| Search                       |                                                   Lightweight full-text substring search across filenames and file contents. | Fast, low-overhead lookup for most small/medium projects.           |
+| Markdown + Mermaid           |                                                        Renders GFM and client-side Mermaid diagrams inside `mermaid` fences. | Rich previews without server-side rendering.                        |
+| Daemon & CLI                 |                                              Start/stop/status plus `--json` machine-readable output for scripts and agents. | Integrates with workflows and automation.                           |
+| Theming & UX                 |                         Light/dark themes, instant floating tooltips appended to `body`, compact path badges for long names. | Tooltips avoid clipping; UI scales to longer path.                  |
+
+### Limitations
+
+- Ignore patterns are glob-only (picomatch). Regex/exact-name modes are not supported.
+- Search is intentionally simple (substring per-line) for clarity and low resource usage.
+- Initial scan of very large directories may take noticeable time; prefer linking smaller subfolders if needed.
+
+## Config
+
+Linked folders and ignore patterns are stored in:
+
+```
+~/.peekmd.json
+
+```
+
+```json
+{
+    "folders": ["/Users/you/docs", "/Users/you/notes"],
+    "ignore": ["**/node_modules/**", "**/dist/**", "**/*.draft.md"]
+}
+```
+
+Created automatically on first use. Can be edited manually.

package/bin/peekmd.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const os = require("node:os");
+const config = require("../src/config");
+const { createServer } = require("../src/server");
+
+const [cmd, ...rest] = process.argv.slice(2);
+const PID_FILE = path.join(os.tmpdir(), "peekmd.pid");
+
+/* ── PID management ────────────────────────────────────────────────── */
+
+const pid = {
+    read() {
+        try {
+            return parseInt(fs.readFileSync(PID_FILE, "utf-8"), 10);
+        } catch {
+            return null;
+        }
+    },
+    write(id) {
+        fs.writeFileSync(PID_FILE, String(id));
+    },
+    clear() {
+        try {
+            fs.unlinkSync(PID_FILE);
+        } catch {}
+    },
+    alive(id) {
+        try {
+            process.kill(id, 0);
+            return true;
+        } catch {
+            return false;
+        }
+    },
+};
+
+/* ── Output ────────────────────────────────────────────────────────── */
+
+const BANNER = `
+┌─────────────────────┐
+│                     │
+│   p e e k  M D     │
+│   ─────────────     │
+│   │ │ │ │ │ │      │
+│                     │
+└─────────────────────┘
+`;
+
+function printTable(headers, rows) {
+    const widths = headers.map(
+        (h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)) + 2,
+    );
+    const line = "  +" + widths.map((w) => "-".repeat(w)).join("+") + "+";
+
+    console.log(line);
+    console.log(
+        "  |" +
+            headers.map((h, i) => (" " + h).padEnd(widths[i])).join("|") +
+            "|",
+    );
+    console.log(line);
+    for (const row of rows)
+        console.log(
+            "  |" +
+                row.map((c, i) => (" " + c).padEnd(widths[i])).join("|") +
+                "|",
+        );
+    console.log(line);
+}
+
+const HELP = `
+  peekmd — Preview Markdown files in the browser
+
+  Server:
+    peekmd start [dir] [dir2] ...   Start server (daemon)
+    peekmd stop                     Stop server
+    peekmd status                   Check if server is running
+
+  Folders:
+    peekmd link <dir> [dir2] ...    Link folders for persistent tracking
+    peekmd unlink <dir> [dir2] ...  Remove folders from tracking
+    peekmd list                     Show all linked folders
+
+  Ignore:
+    peekmd ignore <pattern> ...     Ignore folders/files by glob pattern
+    peekmd unignore <pattern> ...   Remove an ignore pattern
+    peekmd ignored                  Show all active ignore patterns
+
+  Glob Pattern Examples:
+    **/node_modules/**              Ignore all node_modules folders
+    **/*.draft.md                   Ignore all .draft.md files
+    docs/private/**                 Ignore everything under docs/private
+    *.tmp                           Ignore .tmp files at any depth
+
+  AI / Machine-readable output:
+    peekmd list --json              Linked folders as JSON
+    peekmd ignored --json           Ignore patterns as JSON
+    peekmd status --json            Server status as JSON
+    peekmd search <query>           Search files and content (JSON)
+    peekmd files                    List all markdown files (JSON)
+
+  Other:
+    peekmd --help                   Show this help
+
+  Environment:
+    PORT=<number>    Server port (default: 4000)
+
+  Config file: ~/.peekmd.json
+`;
+
+/* ── Helpers ───────────────────────────────────────────────────────── */
+
+const resolveDirs = (dirs) => dirs.map((d) => path.resolve(d));
+const getPort = () => Number(process.env.PORT) || 4000;
+
+function openBrowser(url) {
+    const open =
+        process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+              ? "start"
+              : "xdg-open";
+    require("node:child_process").exec(`${open} ${url}`);
+}
+
+/* ── Commands ──────────────────────────────────────────────────────── */
+
+switch (cmd) {
+    case "--help":
+    case "-h":
+        console.log(HELP);
+        break;
+
+    case "link": {
+        if (!rest.length) {
+            console.error("  Usage: peekmd link <dir> [dir2] ...");
+            process.exit(1);
+        }
+        for (const dir of rest) {
+            const r = config.linkFolder(dir);
+            if (r.error) console.error("  ✗ %s — %s", r.path, r.error);
+            else if (r.added) console.log("  ✓ Linked    %s", r.path);
+            else console.log("  · Already linked    %s", r.path);
+        }
+        break;
+    }
+
+    case "unlink": {
+        if (!rest.length) {
+            console.error("  Usage: peekmd unlink <dir> [dir2] ...");
+            process.exit(1);
+        }
+        for (const dir of rest) {
+            const r = config.unlinkFolder(dir);
+            console.log(
+                r.removed ? "  ✓ Unlinked    %s" : "  · Not linked    %s",
+                r.path,
+            );
+        }
+        break;
+    }
+
+    case "list": {
+        const folders = config.getFolders();
+        if (rest.includes("--json")) {
+            const names = config.getDisplayNames(folders);
+            console.log(
+                JSON.stringify(
+                    folders.map((f, i) => ({ name: names[i], path: f })),
+                    null,
+                    2,
+                ),
+            );
+            break;
+        }
+        if (!folders.length) {
+            console.log("  No folders linked. Run: peekmd link <dir>");
+            break;
+        }
+        const names = config.getDisplayNames(folders);
+        console.log("\n  Linked folders:\n");
+        printTable(
+            ["Name", "Path"],
+            folders.map((f, i) => [names[i], f]),
+        );
+        console.log();
+        break;
+    }
+
+    case "start": {
+        const existing = pid.read();
+        if (existing && pid.alive(existing)) {
+            console.log("  Server already running (PID: %d)", existing);
+            process.exit(0);
+        }
+        pid.clear();
+
+        const child = require("node:child_process").spawn(
+            process.execPath,
+            [__filename, "__serve__", ...rest],
+            {
+                stdio: "ignore",
+                detached: true,
+                env: { ...process.env, PORT: String(getPort()) },
+            },
+        );
+        child.unref();
+        pid.write(child.pid);
+
+        const url = `http://localhost:${getPort()}`;
+        console.log(BANNER);
+        console.log("  %s\n", url);
+        console.log("  To stop: peekmd stop\n");
+        openBrowser(url);
+        break;
+    }
+
+    case "stop": {
+        const id = pid.read();
+        if (!id || !pid.alive(id)) {
+            console.log(
+                id
+                    ? "  PID %d is not running"
+                    : "  No background server running",
+                id,
+            );
+            pid.clear();
+            break;
+        }
+        try {
+            process.kill(id, "SIGTERM");
+        } catch (e) {
+            console.error("  ✗ Failed to stop: %s", e.message);
+            break;
+        }
+        pid.clear();
+        console.log("  ✓ Server stopped");
+        break;
+    }
+
+    case "status": {
+        const id = pid.read();
+        const running = !!(id && pid.alive(id));
+        if (!running && id) pid.clear();
+        if (rest.includes("--json")) {
+            console.log(
+                JSON.stringify({
+                    running,
+                    pid: running ? id : null,
+                    port: Number(process.env.PORT) || 4000,
+                }),
+            );
+            break;
+        }
+        if (running) {
+            console.log(
+                "  ✓ Server running (PID: %d, port: %s)",
+                id,
+                process.env.PORT || 4000,
+            );
+        } else {
+            console.log("  Server not running");
+        }
+        break;
+    }
+
+    case "ignore": {
+        if (!rest.length) {
+            console.error("  Usage: peekmd ignore <pattern> [pattern2] ...");
+            console.error(
+                "  Examples: peekmd ignore '**/node_modules/**' '**/dist/**'",
+            );
+            console.error("           peekmd ignore '**/*.draft.md'");
+            process.exit(1);
+        }
+        for (const p of rest) {
+            const r = config.addIgnorePattern(p);
+            console.log(
+                r.added
+                    ? "  \u2713 Ignoring    %s"
+                    : "  \u00b7 Already ignored    %s",
+                p,
+            );
+        }
+        break;
+    }
+
+    case "unignore": {
+        if (!rest.length) {
+            console.error("  Usage: peekmd unignore <pattern> [pattern2] ...");
+            process.exit(1);
+        }
+        for (const p of rest) {
+            const r = config.removeIgnorePattern(p);
+            console.log(
+                r.removed
+                    ? "  \u2713 Removed    %s"
+                    : "  \u00b7 Not in ignore list    %s",
+                p,
+            );
+        }
+        break;
+    }
+
+    case "ignored": {
+        const patterns = config.getIgnorePatterns();
+        if (rest.includes("--json")) {
+            console.log(
+                JSON.stringify(
+                    patterns.map((p) => ({ pattern: p })),
+                    null,
+                    2,
+                ),
+            );
+            break;
+        }
+        if (!patterns.length) {
+            console.log(
+                "  No ignore patterns set. Run: peekmd ignore <pattern>",
+            );
+            break;
+        }
+        console.log("\n  Ignore patterns (glob):\n");
+        for (const p of patterns) {
+            console.log("    %s", p);
+        }
+        console.log();
+        break;
+    }
+
+    case "search": {
+        /* Search across linked folders — outputs JSON for AI agents */
+        const query = rest.filter((a) => !a.startsWith("--")).join(" ");
+        if (!query) {
+            console.error("  Usage: peekmd search <query>");
+            process.exit(1);
+        }
+        const { searchCli } = require("../src/server");
+        searchCli(config.getFolders(), query)
+            .then((r) => console.log(JSON.stringify(r, null, 2)))
+            .catch(() => process.exit(1));
+        break;
+    }
+
+    case "files": {
+        /* List all markdown files across linked folders — JSON output */
+        const { listFilesCli } = require("../src/server");
+        listFilesCli(config.getFolders())
+            .then((r) => console.log(JSON.stringify(r, null, 2)))
+            .catch(() => process.exit(1));
+        break;
+    }
+
+    case "__serve__": {
+        /* Internal: spawned by 'start' as a detached daemon */
+        const extra = rest.length ? resolveDirs(rest) : [];
+        const port = getPort();
+
+        createServer({ port, extraDirs: extra }).catch(() => process.exit(1));
+        break;
+    }
+
+    default: {
+        console.log(HELP);
+        break;
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@astlw/peekmd",
+    "version": "1.0.0",
+    "description": "A CLI tool that renders Markdown files in the browser and live-reloads on every file save.",
+    "author": "AST-LW",
+    "license": "MIT",
+    "private": false,
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/AST-LW/peekmd.git"
+    },
+    "homepage": "https://github.com/AST-LW/peekmd#readme",
+    "bugs": {
+        "url": "https://github.com/AST-LW/peekmd/issues"
+    },
+    "bin": {
+        "peekmd": "./bin/peekmd.js"
+    },
+    "files": [
+        "bin",
+        "src",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "keywords": [
+        "markdown",
+        "markdown-server",
+        "markdown-preview",
+        "mermaid",
+        "cli",
+        "viewer",
+        "documentation",
+        "live-reload"
+    ],
+    "dependencies": {
+        "chokidar": "^3.6.0",
+        "express": "^4.21.0",
+        "picomatch": "^4.0.3",
+        "ws": "^8.18.0"
+    }
+}

package/src/config.js

@@ -0,0 +1,143 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const picomatch = require("picomatch");
+
+const CONFIG_PATH = path.join(require("node:os").homedir(), ".peekmd.json");
+
+function read() {
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+    } catch {
+        return { folders: [] };
+    }
+}
+
+function write(data) {
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2) + "\n");
+}
+
+function getFolders() {
+    return read().folders;
+}
+
+function linkFolder(dir) {
+    const abs = path.resolve(dir);
+    if (!fs.existsSync(abs))
+        return { added: false, path: abs, error: "path does not exist" };
+    if (!fs.statSync(abs).isDirectory())
+        return { added: false, path: abs, error: "not a directory" };
+
+    const data = read();
+    if (data.folders.includes(abs)) return { added: false, path: abs };
+    data.folders.push(abs);
+    write(data);
+    return { added: true, path: abs };
+}
+
+function unlinkFolder(dir) {
+    const abs = path.resolve(dir);
+    const data = read();
+    const idx = data.folders.indexOf(abs);
+    if (idx === -1) return { removed: false, path: abs };
+    data.folders.splice(idx, 1);
+    write(data);
+    return { removed: true, path: abs };
+}
+
+function getDisplayNames(folders) {
+    const counts = {};
+    for (const f of folders) {
+        const b = path.basename(f);
+        counts[b] = (counts[b] || 0) + 1;
+    }
+    return folders.map((f) => {
+        const b = path.basename(f);
+        return counts[b] > 1 ? `${path.basename(path.dirname(f))}/${b}` : b;
+    });
+}
+
+/* ── Ignore patterns ───────────────────────────────────────────────── */
+
+const DEFAULT_IGNORE = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/__pycache__/**",
+];
+
+function ensureDefaults() {
+    const data = read();
+    if (!data.ignore) {
+        data.ignore = [...DEFAULT_IGNORE];
+        write(data);
+    }
+}
+
+function getIgnorePatterns() {
+    return read().ignore || DEFAULT_IGNORE;
+}
+
+function addIgnorePattern(pattern) {
+    const data = read();
+    if (!data.ignore) data.ignore = [];
+    if (data.ignore.includes(pattern)) return { added: false, pattern };
+    data.ignore.push(pattern);
+    write(data);
+    clearGlobCache();
+    return { added: true, pattern };
+}
+
+function removeIgnorePattern(pattern) {
+    const data = read();
+    if (!data.ignore) return { removed: false, pattern };
+    const idx = data.ignore.indexOf(pattern);
+    if (idx === -1) return { removed: false, pattern };
+    data.ignore.splice(idx, 1);
+    write(data);
+    clearGlobCache();
+    return { removed: true, pattern };
+}
+
+/* pre-compiled glob cache so we don't re-parse every call */
+const _globCache = new Map();
+
+function clearGlobCache() {
+    _globCache.clear();
+}
+
+function getGlobMatcher(pattern) {
+    if (!_globCache.has(pattern)) {
+        _globCache.set(pattern, picomatch(pattern, { dot: true }));
+    }
+    return _globCache.get(pattern);
+}
+
+/**
+ * Test whether a relative path should be ignored.
+ * All patterns are treated as glob patterns (picomatch syntax).
+ */
+function isIgnored(relPath) {
+    const patterns = getIgnorePatterns();
+    for (const p of patterns) {
+        if (getGlobMatcher(p)(relPath)) return true;
+    }
+    return false;
+}
+
+module.exports = {
+    getFolders,
+    linkFolder,
+    unlinkFolder,
+    getDisplayNames,
+    ensureDefaults,
+    getIgnorePatterns,
+    addIgnorePattern,
+    removeIgnorePattern,
+    isIgnored,
+    clearGlobCache,
+    CONFIG_PATH,
+};