@choonkeat/md-serve 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# md-serve
+
+Tiny static file server that renders Markdown (`.md`, `.markdown`) as
+GitHub-styled HTML. Single Go binary, distributed via npm with native
+binaries for Linux / macOS / Windows on x64 and arm64.
+
+## Install
+
+```sh
+npm install -g @choonkeat/md-serve
+# or one-shot:
+npx @choonkeat/md-serve
+```
+
+(The published name is scoped — npm rejected the unscoped `md-serve`
+as too similar to an existing package. The installed binary is still
+called `md-serve`.)
+
+## Usage
+
+```sh
+md-serve                  # serve $PWD on :$PORT (or :8080), live-reload on
+md-serve -dir ./docs      # serve a specific directory
+md-serve -addr :3000      # bind to a specific address
+md-serve -no-live         # disable the live-reload poller
+md-serve -version
+```
+
+## Behavior
+
+- `.md` / `.markdown` files render as HTML using
+  [goldmark](https://github.com/yuin/goldmark) with GFM, styled with
+  [github-markdown-css](https://github.com/sindresorhus/github-markdown-css).
+  Fenced code blocks are syntax-highlighted via
+  [chroma](https://github.com/alecthomas/chroma) (200+ languages).
+- Directories show a generated listing with **Name / Size / Modified**
+  columns. If `index.md` / `README.md` / `readme.md` / `index.markdown`
+  is present, it's rendered below the listing GitHub-style. If only
+  `index.html` is present, it's served raw.
+- Source files (`.go`, `.py`, `.json`, `.yaml`, `.toml`, `Dockerfile`,
+  `Makefile`, ...) render as syntax-highlighted HTML with linkable line
+  numbers (`/main.go#L42`). Append `?raw=1` to any URL to bypass and
+  fetch the byte-for-byte original. Files larger than 1 MiB or that
+  look binary skip highlighting and stream raw.
+- Everything else is served byte-for-byte.
+- Dotfiles are hidden from listings.
+- Path traversal is blocked: requests are rejected if they resolve
+  outside the served root.
+- Live-reload is on by default: rendered pages poll a tiny endpoint
+  once a second and reload themselves when the underlying file's mtime
+  changes. Pass `-no-live` to disable (e.g. for production-style
+  serving where you don't want the extra requests).
+
+## Develop
+
+```sh
+make build              # cross-compile all 6 platform binaries → npm-platforms/
+make test               # go vet
+make publish-dry        # rehearse the npm publish
+make publish            # ship to npm
+make bump VERSION=x.y.z # sync version across package.json + optionalDependencies
+```
+
+The npm package layout: a thin shim (`bin/md-serve.js`) selects the
+right `@choonkeat/md-serve-<platform>-<arch>` optionalDependency at
+runtime, falling back to a locally built binary in `npm-platforms/`
+during development.
+
+## License
+
+MIT

package/bin/md-serve.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+import { existsSync, chmodSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const PLATFORM_MAP = {
+  linux: "linux",
+  darwin: "darwin",
+  win32: "win32",
+};
+
+const ARCH_MAP = {
+  x64: "x64",
+  arm64: "arm64",
+};
+
+const platform = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+
+if (!platform || !arch) {
+  console.error(
+    `Unsupported platform: ${process.platform}-${process.arch}\n` +
+      `md-serve supports: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64, win32-arm64`
+  );
+  process.exit(1);
+}
+
+const pkgName = `@choonkeat/md-serve-${platform}-${arch}`;
+const binName = process.platform === "win32" ? "md-serve.exe" : "md-serve";
+
+// Prefer local build in npm-platforms/ (development) over npm-installed package.
+// npm-platforms/ is not published to npm, so this only takes effect during local dev.
+const localPath = join(__dirname, "..", "npm-platforms", `${platform}-${arch}`, "bin", binName);
+
+let binPath;
+if (existsSync(localPath)) {
+  binPath = localPath;
+} else {
+  try {
+    const pkgDir = dirname(require.resolve(`${pkgName}/package.json`));
+    binPath = join(pkgDir, "bin", binName);
+  } catch {
+    console.error(
+      `Could not find package ${pkgName}.\n` +
+        `Make sure it is installed — this usually means your platform is supported\n` +
+        `but the optional dependency was not installed.\n\n` +
+        `Try: npm install ${pkgName}\n` +
+        `Or run: npx @choonkeat/md-serve`
+    );
+    process.exit(1);
+  }
+}
+
+if (!existsSync(binPath)) {
+  console.error(`Binary not found at ${binPath}`);
+  process.exit(1);
+}
+
+function run() {
+  const result = spawnSync(binPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    return result;
+  }
+  process.exit(result.status ?? 1);
+}
+
+let result = run();
+
+// Handle EACCES by chmod +x and retrying
+if (result.error && result.error.code === "EACCES") {
+  try {
+    chmodSync(binPath, 0o755);
+  } catch (e) {
+    console.error(`Failed to chmod +x ${binPath}: ${e.message}`);
+    process.exit(1);
+  }
+  result = run();
+}
+
+if (result.error) {
+  console.error(`Failed to start md-serve: ${result.error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@choonkeat/md-serve",
+  "version": "0.1.0",
+  "description": "Tiny static file server that renders Markdown as GitHub-styled HTML",
+  "type": "module",
+  "bin": {
+    "md-serve": "bin/md-serve.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(__dirname,'bin','md-serve.js'),0o755)}catch(e){}\"",
+    "prepare": "node scripts/prepare-local-build.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/choonkeat/md-serve.git"
+  },
+  "license": "MIT",
+  "optionalDependencies": {
+    "@choonkeat/md-serve-darwin-arm64": "0.1.0",
+    "@choonkeat/md-serve-darwin-x64": "0.1.0",
+    "@choonkeat/md-serve-linux-arm64": "0.1.0",
+    "@choonkeat/md-serve-linux-x64": "0.1.0",
+    "@choonkeat/md-serve-win32-arm64": "0.1.0",
+    "@choonkeat/md-serve-win32-x64": "0.1.0"
+  }
+}