promaster 1.1.0 → 1.3.0

package/README.md

@@ -1,7 +1,8 @@
 # promaster
 
-Interactive CLI to browse and download Markdown from a **public GitHub repo**,
-grouped into three categories: **blog**, **memory**, **books**.
+Interactive CLI to browse Markdown from a **public GitHub repo**, grouped into
+three categories: **blog**, **memory**, **books**. Each selected file is
+rendered to a styled, standalone **HTML** page — click it to open in a browser.
 
 The package ships only the CLI. Your Markdown content lives in your own GitHub
 repo and is fetched at runtime — it is never bundled into npm.
@@ -32,7 +33,12 @@ promaster list
 1. Pick a category: `blog` / `memory` / `books`.
 2. Files are listed newest → oldest (by last git commit date).
 3. Toggle one or more with space, confirm with enter.
-4. Selected files download to `./promaster-data/<category>/`, where your app reads them.
+4. Each selection is converted to HTML and saved to
+   `./promaster-data/<category>/<name>.html`.
+5. The CLI then offers to open the saved file(s) in your default browser.
+
+Open any saved `.html` later by double-clicking it — it renders fully offline
+(styles are inlined, with light/dark support).
 
 ## Configuration
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "promaster",
-  "version": "1.1.0",
-  "description": "Interactive CLI to browse and download Markdown (blog/memory/books) from a public GitHub repo.",
+  "version": "1.3.0",
+  "description": "Interactive CLI to browse Markdown (blog/memory/books) from a public GitHub repo and save it as browser-ready HTML.",
   "type": "module",
   "bin": {
     "promaster": "./bin/promaster.js"
@@ -23,10 +23,12 @@
     "markdown",
     "github",
     "blog",
-    "notes"
+    "notes",
+    "html"
   ],
   "license": "MIT",
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0"
+    "@inquirer/prompts": "^7.0.0",
+    "marked": "^14.0.0"
   }
 }

package/src/commands/list.js

@@ -1,8 +1,11 @@
-import { select, checkbox } from "@inquirer/prompts";
+import { select, checkbox, confirm, input } from "@inquirer/prompts";
 import { resolve, dirname } from "node:path";
+import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { resolveRepo, CATEGORIES } from "../config.js";
 import { listMarkdown, lastCommitDate, fetchRaw, HttpError } from "../github.js";
-import { save, OUTPUT_ROOT } from "../download.js";
+import { save, saveTemp, OUTPUT_ROOT } from "../download.js";
+import { openInBrowser } from "../open.js";
 
 const CONCURRENCY = 5;
 
@@ -53,15 +56,72 @@ export async function runList() {
     return;
   }
 
+  // books: open immediately, never persist — delete the temp files on exit.
+  if (category === "books") {
+    await openEphemeral(picked, ctx);
+    return;
+  }
+
   const saved = [];
   for (const file of picked) {
     const content = await fetchRaw(file.download_url, ctx);
     saved.push(await save(category, file, content));
   }
 
-  console.log("\nSaved:");
+  console.log("\nSaved (HTML — click to open in a browser):");
   for (const p of saved) console.log(`  ${p}`);
   console.log(`\nOutput dir: ${resolve(process.cwd(), OUTPUT_ROOT, category)}`);
+
+  const open = await confirm({
+    message: `Open ${saved.length === 1 ? "it" : "them"} in your browser now?`,
+    default: true,
+  });
+  if (open) {
+    for (const p of saved) openInBrowser(p);
+  }
+}
+
+// Render picks to OS temp, auto-open in the browser, then delete once the
+// user is done (Enter) or aborts (Ctrl+C). Nothing is left on disk.
+async function openEphemeral(picked, ctx) {
+  const dirs = [];
+  const cleanup = () => {
+    while (dirs.length) {
+      try {
+        rmSync(dirs.pop(), { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  };
+
+  const onSigint = () => {
+    cleanup();
+    process.exit(130);
+  };
+  process.on("SIGINT", onSigint);
+
+  try {
+    for (const file of picked) {
+      const content = await fetchRaw(file.download_url, ctx);
+      const { path, dir } = await saveTemp(file, content);
+      dirs.push(dir);
+      openInBrowser(path);
+      console.log(`Opened in browser: ${file.name}`);
+    }
+
+    console.log("\nThese are temporary — nothing is saved to disk.");
+    await input({
+      message: `Press Enter when you're done to delete the temporary file${
+        picked.length === 1 ? "" : "s"
+      }`,
+    });
+  } finally {
+    process.off("SIGINT", onSigint);
+    for (const dir of dirs.splice(0)) {
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
 }
 
 export { HttpError };

package/src/download.js

@@ -1,5 +1,7 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { basename, resolve } from "node:path";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { mdToHtml } from "./render.js";
 
 export const OUTPUT_ROOT = "promaster-data";
 
@@ -15,12 +17,43 @@ export function safeName(name) {
 }
 
 /**
- * Save raw content under ./promaster-data/<category>/<name>. Returns absolute path.
+ * Safe basename with its extension replaced by ".html".
+ */
+export function htmlName(name) {
+  const base = safeName(name);
+  const ext = extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  return `${stem}.html`;
+}
+
+/**
+ * Render markdown to a styled HTML document and save it under
+ * ./promaster-data/<category>/<name>.html. Returns the absolute path.
  */
 export async function save(category, file, content) {
   const dir = resolve(process.cwd(), OUTPUT_ROOT, safeName(category));
   await mkdir(dir, { recursive: true });
-  const dest = resolve(dir, safeName(file.name));
-  await writeFile(dest, content, "utf8");
+  const base = safeName(file.name);
+  const ext = extname(base);
+  const title = ext ? base.slice(0, -ext.length) : base;
+  const html = mdToHtml(content, { title });
+  const dest = resolve(dir, htmlName(file.name));
+  await writeFile(dest, html, "utf8");
   return dest;
 }
+
+/**
+ * Render markdown to HTML in a fresh OS temp directory (never under
+ * promaster-data). Returns { path, dir } so the caller can delete `dir`
+ * once the user is done viewing — nothing is persisted.
+ */
+export async function saveTemp(file, content) {
+  const dir = await mkdtemp(resolve(tmpdir(), "promaster-"));
+  const base = safeName(file.name);
+  const ext = extname(base);
+  const title = ext ? base.slice(0, -ext.length) : base;
+  const html = mdToHtml(content, { title });
+  const path = resolve(dir, htmlName(file.name));
+  await writeFile(path, html, "utf8");
+  return { path, dir };
+}

package/src/open.js

@@ -0,0 +1,30 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+
+/**
+ * Open a file/path in the OS default application (browser for .html).
+ * Non-blocking and best-effort: failures are reported but never throw.
+ */
+export function openInBrowser(filePath) {
+  let cmd, args;
+  if (platform === "win32") {
+    // empty "" is the window title arg required by `start`
+    cmd = "cmd";
+    args = ["/c", "start", "", filePath];
+  } else if (platform === "darwin") {
+    cmd = "open";
+    args = [filePath];
+  } else {
+    cmd = "xdg-open";
+    args = [filePath];
+  }
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    child.on("error", (err) => {
+      console.error(`Could not open ${filePath}: ${err.message}`);
+    });
+    child.unref();
+  } catch (err) {
+    console.error(`Could not open ${filePath}: ${err.message}`);
+  }
+}

package/src/render.js

@@ -0,0 +1,77 @@
+import { marked } from "marked";
+
+const ESCAPE = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+
+function escapeHtml(str) {
+  return String(str).replace(/[&<>"]/g, (ch) => ESCAPE[ch]);
+}
+
+const STYLE = `
+  :root { color-scheme: light dark; }
+  body {
+    max-width: 760px;
+    margin: 2.5rem auto;
+    padding: 0 1.25rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    line-height: 1.65;
+    color: #1a1a1a;
+    background: #ffffff;
+  }
+  h1, h2, h3, h4 { line-height: 1.25; margin-top: 1.8em; }
+  h1 { border-bottom: 1px solid #e1e4e8; padding-bottom: .3em; }
+  a { color: #0969da; }
+  code {
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    font-size: .9em;
+    background: rgba(127,127,127,.15);
+    padding: .15em .35em;
+    border-radius: 4px;
+  }
+  pre {
+    background: #f6f8fa;
+    padding: 1rem;
+    border-radius: 8px;
+    overflow-x: auto;
+  }
+  pre code { background: none; padding: 0; }
+  blockquote {
+    margin: 0;
+    padding: 0 1em;
+    color: #57606a;
+    border-left: .25em solid #d0d7de;
+  }
+  table { border-collapse: collapse; width: 100%; }
+  th, td { border: 1px solid #d0d7de; padding: .5em .75em; }
+  img { max-width: 100%; }
+  @media (prefers-color-scheme: dark) {
+    body { color: #e6edf3; background: #0d1117; }
+    h1 { border-bottom-color: #30363d; }
+    a { color: #4493f8; }
+    pre { background: #161b22; }
+    blockquote { color: #8b949e; border-left-color: #30363d; }
+    th, td { border-color: #30363d; }
+  }
+`;
+
+/**
+ * Convert markdown text into a standalone, styled HTML document.
+ * @param {string} markdown raw markdown source
+ * @param {{ title?: string }} [opts]
+ * @returns {string} full HTML document
+ */
+export function mdToHtml(markdown, { title = "Document" } = {}) {
+  const body = marked.parse(String(markdown));
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}