@zvndev/darkmown 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.20.0 — 2026-06-26
+
+Engineering hardening: a real programmatic API, plus a gold-standard pass on tooling, tests, and internals. No behavior change for existing sites — the runtime is byte-for-byte the same (~5.8 KB gzipped).
+
+- **Programmatic API.** `@zvndev/darkmown` now ships a proper entry point: `import { buildSite, compilePage, compileDocument, parseFrontmatter, escapeHtml, … } from "@zvndev/darkmown"` resolves through an `exports` map and a `src/index.js` barrel that mirrors the public surface already declared in `types/index.d.ts`. The package was CLI-only before; the `darkmown` CLI is unchanged.
+- **Compiler internals split.** The ~2,900-line `src/compiler.js` is now a `src/compiler/` folder along its existing seams (page shell, frontmatter, includes, interpolation, predicates, markdown plugin, loops, directives, body). Public exports and output are identical — `src/compiler.js` stays as a thin re-export barrel. Purely internal.
+- **Sharper compile errors.** Malformed-directive errors now report `file:line` (matching the unclosed-block errors that already did), and action-literal failures name the offending page. Easier to trace a mistake back to its source.
+- **Lint + format with Biome.** Added Biome (one binary, lint + format) with `npm run lint` / `npm run format:check`, a `lint` CI job, and a husky + lint-staged pre-commit that checks staged files. `src/runtime.js` is excluded from the formatter so the byte budget is never moved by a reformat. Style commands are documented in CONTRIBUTING.md.
+- **100% line coverage, CI-gated.** The test suite now covers every line of `src/`, and the coverage gate is raised from 90% to 100%. Covering the CLI and dev-server paths surfaced and fixed two real bugs: symlinked-bin entry-point detection and a dev-server response that wrote headers before reading the file.
+- **Runtime size trend.** A committed `.size-snapshot.json` baseline lets CI report the gzipped-runtime delta on every change, alongside the existing hard < 6 KB gate.
+- **Fixed a production-breaking `vercel.json`.** An invalid `comment` property was rejected by Vercel's strict schema and failed every deploy before install; removed, with a regression test that rejects any non-allowlisted key in a `headers[]` rule.
+
 ## 0.19.0 — 2026-06-25
 
 Post-review sprint: deeper reactive loops, hardened deploys, and OS-aware theming.

package/README.md

@@ -7,7 +7,7 @@
 
 **[darkmown.com](https://darkmown.com)** · Markdown that runs.
 
-Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~5.7 KB gzipped, CI-enforced under 6 KB.
+Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~5.8 KB gzipped, CI-enforced under 6 KB.
 
 ## Quick start
 
@@ -52,7 +52,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 - Files or folders starting with `.`, `-`, or `_` are hidden from routing.
 - `site/_` is the include shelf for `@include /name.wd`.
 - Matching `page.skin` and `page.js` colocate styling and behavior by basename.
-- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~5.7 KB gzipped, CI-enforced under 6 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~5.8 KB gzipped, CI-enforced under 6 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,26 +10,41 @@
   "bin": {
     "darkmown": "./src/cli.js"
   },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
   "types": "./types/index.d.ts",
   "scripts": {
     "build": "node src/cli.js build",
     "runtime:size": "node -e \"const fs=require('fs'),zlib=require('zlib'); const size=zlib.gzipSync(fs.readFileSync('dist/__wd/runtime.js')).length; console.log('shipped runtime gzipped: '+size+' bytes (budget: 6144)'); if (size >= 6144) process.exit(1)\"",
     "dev": "node src/cli.js dev",
     "test": "node --test tests/*.test.js",
-    "test:cov": "node scripts/test-coverage-gate.mjs 90",
+    "test:cov": "node scripts/test-coverage-gate.mjs 100",
     "test:e2e": "playwright test",
     "test:extension": "npm --prefix editors/vscode ci && npm --prefix editors/vscode test",
     "pack:extension": "cd editors/vscode && npx --yes @vscode/vsce package",
     "typecheck": "tsc --noEmit",
     "types": "tsc -p tsconfig.types.json",
     "smoke": "node scripts/smoke-consumer.mjs",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "size:check": "node scripts/size-check.mjs",
+    "prepare": "husky || true",
     "prepublish:check": "npm run typecheck && npm run test:cov && npm run build && npm run runtime:size && npm audit --audit-level=high && npm run smoke",
-    "prepublishOnly": "npm run prepublish:check"
+    "prepublishOnly": "npm run prepublish:check",
+    "og": "node scripts/og-image.mjs"
+  },
+  "lint-staged": {
+    "*.{js,json}": "biome check --no-errors-on-unmatched --files-ignore-unknown=true"
   },
   "files": [
     "src",
     "types",
     "site",
+    "!site/_/og.png",
     "docs/cli.md",
     "docs/spec-alignment.md",
     "AGENTS.md",
@@ -46,9 +61,12 @@
     "markdown-it": "^14.2.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
     "@playwright/test": "^1.49.0",
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^26.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
     "typescript": "^6.0.3"
   },
   "repository": {

package/src/builder.js

@@ -60,7 +60,9 @@ export function buildSite(cwd = process.cwd()) {
       file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
       assets: {
         skins: [...page.assets.skins],
-        scripts: page.assets.runtime ? ["/__wd/runtime.js", ...page.assets.scripts] : [...page.assets.scripts],
+        scripts: page.assets.runtime
+          ? ["/__wd/runtime.js", ...page.assets.scripts]
+          : [...page.assets.scripts],
         runtime: page.assets.runtime
       }
     });
@@ -101,13 +103,15 @@ export function buildSite(cwd = process.cwd()) {
  * @returns {string}
  */
 export function stripRuntimeComments(source) {
-  return source
-    // JSDoc blocks — type annotations the browser never needs.
-    .replace(/\/\*\*[\s\S]*?\*\//g, "")
-    // Whole-line `//` comments — developer notes that don't belong in the download.
-    .replace(/^[ \t]*\/\/.*$/gm, "")
-    // Drop the now blank/whitespace-only lines the removals leave behind.
-    .replace(/^[ \t]*\n/gm, "");
+  return (
+    source
+      // JSDoc blocks — type annotations the browser never needs.
+      .replace(/\/\*\*[\s\S]*?\*\//g, "")
+      // Whole-line `//` comments — developer notes that don't belong in the download.
+      .replace(/^[ \t]*\/\/.*$/gm, "")
+      // Drop the now blank/whitespace-only lines the removals leave behind.
+      .replace(/^[ \t]*\n/gm, "")
+  );
 }
 
 /**
@@ -126,10 +130,10 @@ export function stripRuntimeComments(source) {
  * @returns {string}
  */
 export function renderCloudflareHeaders(manifest) {
-  const baseLines = Object.entries(BASE_SECURITY_HEADERS).map(([name, value]) => `  ${name}: ${value}`);
-  const blocks = [
-    ["/*", [...baseLines, `  Content-Security-Policy: ${REACTIVE_CSP}`]]
-  ];
+  const baseLines = Object.entries(BASE_SECURITY_HEADERS).map(
+    ([name, value]) => `  ${name}: ${value}`
+  );
+  const blocks = [["/*", [...baseLines, `  Content-Security-Policy: ${REACTIVE_CSP}`]]];
 
   for (const entry of manifest) {
     if (entry.assets.runtime) continue; // reactive routes keep the catch-all (relaxed) CSP
@@ -169,7 +173,7 @@ function defaultNotFoundHtml() {
     "<body>",
     "<main>",
     "<h1>Page not found</h1>",
-    "<p>That route does not exist. <a href=\"/\">Back to home</a>.</p>",
+    '<p>That route does not exist. <a href="/">Back to home</a>.</p>',
     "</main>",
     "</body>",
     "</html>",
@@ -243,7 +247,9 @@ function emitPageAssets(paths) {
     if (hasHiddenPathSegment(rel) || fs.lstatSync(file).isSymbolicLink()) continue;
     const out = path.join(paths.distRoot, rel);
     if (fs.existsSync(out)) {
-      console.warn(`hint: page asset "${rel}" skipped — a built route already emits /${rel.replaceAll(path.sep, "/")}`);
+      console.warn(
+        `hint: page asset "${rel}" skipped — a built route already emits /${rel.replaceAll(path.sep, "/")}`
+      );
       continue;
     }
     fs.mkdirSync(path.dirname(out), { recursive: true });

package/src/cli.js

@@ -10,38 +10,101 @@ import { initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
-// Bare `darkmown` prints help (discovery) rather than silently building — a new
-// user typing the command alone expects to see what it can do, not a no-op build.
-const command = process.argv[2] || "help";
-
-if (command === "help" || command === "--help" || command === "-h") {
-  printHelp();
-} else if (command === "version" || command === "--version" || command === "-v") {
-  const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  console.log(pkg.version);
-} else if (command === "init") {
-  try {
-    const target = process.argv[3] || ".";
-    const result = initProject(path.resolve(process.cwd(), target));
-    const relativeRoot = path.relative(process.cwd(), result.root) || ".";
-    console.log(`Created Darkmown project at ${relativeRoot}`);
-    console.log(`Next: ${nextStep(relativeRoot)}`);
-  } catch (error) {
-    failClean(error);
+
+/**
+ * Run the Darkmown CLI. Extracted from the top-level script so every command
+ * branch is unit-testable in-process: it never reads `process.argv` or calls
+ * `process.exit` directly. Instead it takes the argv tail and an injectable
+ * environment, RETURNS a value (and a server/close handle for `dev`/`serve`),
+ * and throws `CliError` for the failure paths the binary maps to exit code 1.
+ *
+ * The thin top-level wrapper below preserves identical binary behavior: it reads
+ * `process.argv`, calls `run`, prints `CliError` messages the same way the old
+ * inline `failClean`/`console.error` did, and exits with the right code.
+ *
+ * @typedef {object} RunEnv
+ * @property {string} [cwd] Working directory (defaults to `process.cwd()`).
+ * @property {(message?: unknown, ...rest: unknown[]) => void} [log] stdout sink.
+ * @property {(message?: unknown, ...rest: unknown[]) => void} [warn] stderr (warn) sink.
+ * @property {(message?: unknown, ...rest: unknown[]) => void} [error] stderr (error) sink.
+ *
+ * @param {string[]} argv The argv tail (i.e. `process.argv.slice(2)`).
+ * @param {RunEnv} [env]
+ * @returns {Promise<{ command: string, server?: import("node:http").Server, close?: () => Promise<void> }>}
+ */
+export async function run(argv, env = {}) {
+  const cwd = env.cwd ?? process.cwd();
+  const log = env.log ?? console.log;
+  const warn = env.warn ?? console.warn;
+  const error = env.error ?? console.error;
+  // Bare `darkmown` prints help (discovery) rather than silently building — a new
+  // user typing the command alone expects to see what it can do, not a no-op build.
+  const command = argv[0] || "help";
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    log(helpText());
+    return { command: "help" };
   }
-} else if (command === "build") {
-  try {
-    const result = buildSite();
-    console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
-  } catch (error) {
-    // A compile error has a clear, file-pathed message — print just that, not a
-    // Node stack trace, so a typo reads as "fix your page", not "the tool crashed".
-    failClean(error);
+  if (command === "version" || command === "--version" || command === "-v") {
+    const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    log(pkg.version);
+    return { command: "version" };
+  }
+  if (command === "init") {
+    const target = argv[1] || ".";
+    const result = initProject(path.resolve(cwd, target));
+    const relativeRoot = path.relative(cwd, result.root) || ".";
+    log(`Created Darkmown project at ${relativeRoot}`);
+    log(`Next: ${nextStep(relativeRoot)}`);
+    return { command: "init" };
+  }
+  if (command === "build") {
+    const result = buildSite(cwd);
+    log(`Built ${result.routes.length} routes into ${path.relative(cwd, result.distRoot)}`);
+    return { command: "build" };
+  }
+  if (command === "dev") {
+    return startDevServer({ cwd, log, warn, error });
+  }
+  if (command === "serve") {
+    return startPreviewServer({ cwd, log, error });
+  }
+  // No command matched: report it, show help, and fail like the binary always
+  // did (exit 1). `silent` keeps `main` from re-printing a `✗` line on top.
+  error(`Unknown command: ${command}`);
+  log(helpText());
+  throw new CliError(`Unknown command: ${command}`, { silent: true });
+}
+
+/**
+ * An error whose message is already user-facing. The binary prints it (prefixed
+ * with `✗` unless `silent`) and exits 1 — never a Node stack trace.
+ */
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ silent?: boolean }} [options] `silent` skips the `✗`-prefixed print
+   *   (used when the message was already shown, e.g. unknown command + help).
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.silent = Boolean(options.silent);
   }
-} else if (command === "dev") {
+}
+
+/**
+ * Start the live-compiler dev server. Builds once (recording, not crashing on, a
+ * broken initial build), watches `site/` and `src/`, and serves dist with the
+ * dev client + SSE reload channel injected. Returns the server and a clean
+ * `close()` that tears down the watchers and the rebuild debounce timer.
+ * @param {{ cwd: string, log: typeof console.log, warn: typeof console.warn, error: typeof console.error }} io
+ * @returns {Promise<{ command: "dev", server: import("node:http").Server, close: () => Promise<void> }>}
+ */
+function startDevServer({ cwd, log, warn, error }) {
   const port = Number(process.env.PORT || 5173);
   const host = process.env.HOST || "127.0.0.1";
-  const distRoot = path.join(process.cwd(), "dist");
+  const distRoot = path.join(cwd, "dist");
   /** @type {Set<import("node:http").ServerResponse>} */
   const clients = new Set();
   /** @type {ReturnType<typeof setTimeout> | undefined} */
@@ -53,10 +116,10 @@ if (command === "help" || command === "--help" || command === "-h") {
   // and thus the error overlay — comes up. Record the error so new SSE clients
   // see it on connect; the next successful rebuild clears it via `reload`.
   try {
-    buildSite();
-  } catch (error) {
-    lastBuildError = (error instanceof Error ? error.message : String(error)).trim();
-    console.error(lastBuildError);
+    buildSite(cwd);
+  } catch (err) {
+    lastBuildError = (err instanceof Error ? err.message : String(err)).trim();
+    error(lastBuildError);
   }
 
   // Rebuild in a child process so changes to Darkmown's own src/ always load
@@ -65,26 +128,32 @@ if (command === "help" || command === "--help" || command === "-h") {
     clearTimeout(timer);
     timer = setTimeout(() => {
       const started = performance.now();
-      execFile(process.execPath, [cliPath, "build"], { cwd: process.cwd() }, (error, stdout, stderr) => {
-        if (error) {
-          const message = (stderr || stdout || String(error)).trim();
+      execFile(process.execPath, [cliPath, "build"], { cwd }, (err, stdout, stderr) => {
+        if (err) {
+          const message = (stderr || stdout || String(err)).trim();
           lastBuildError = message;
-          console.error(message);
-          broadcast(clients, `event: builderror\ndata: ${JSON.stringify({ message: message.slice(0, 4000) })}\n\n`);
+          error(message);
+          broadcast(
+            clients,
+            `event: builderror\ndata: ${JSON.stringify({ message: message.slice(0, 4000) })}\n\n`
+          );
           return;
         }
         lastBuildError = undefined;
         const elapsed = Math.round(performance.now() - started);
-        if (stderr.trim()) console.warn(stderr.trim());
+        if (stderr.trim()) warn(stderr.trim());
         broadcast(clients, `event: reload\ndata: ${JSON.stringify({ elapsed })}\n\n`);
-        console.log(`${stdout.trim().split("\n").at(-1)} (${elapsed}ms)`);
+        log(`${stdout.trim().split("\n").at(-1)} (${elapsed}ms)`);
       });
     }, 30);
   };
 
+  /** @type {import("node:fs").FSWatcher[]} */
+  const watchers = [];
   for (const dir of ["site", "src"]) {
-    if (fs.existsSync(dir)) {
-      fs.watch(dir, { recursive: true }, rebuild);
+    const abs = path.join(cwd, dir);
+    if (fs.existsSync(abs)) {
+      watchers.push(fs.watch(abs, { recursive: true }, rebuild));
     }
   }
 
@@ -102,7 +171,9 @@ if (command === "help" || command === "--help" || command === "-h") {
         // Replay a broken build to clients that connect while it's still failing,
         // so the overlay shows even after a startup or pre-connect compile error.
         if (lastBuildError) {
-          res.write(`event: builderror\ndata: ${JSON.stringify({ message: lastBuildError.slice(0, 4000) })}\n\n`);
+          res.write(
+            `event: builderror\ndata: ${JSON.stringify({ message: lastBuildError.slice(0, 4000) })}\n\n`
+          );
         }
         req.on("close", () => clients.delete(res));
         return;
@@ -117,39 +188,67 @@ if (command === "help" || command === "--help" || command === "-h") {
         req.on("data", (chunk) => (body += chunk));
         req.on("end", () => {
           res.writeHead(200, { "content-type": "application/json" });
-          res.end(JSON.stringify({
-            ok: true,
-            received: Object.fromEntries(new URLSearchParams(body)),
-            at: new Date().toISOString()
-          }));
+          res.end(
+            JSON.stringify({
+              ok: true,
+              received: Object.fromEntries(new URLSearchParams(body)),
+              at: new Date().toISOString()
+            })
+          );
         });
         return;
       }
       serveDev(distRoot, url, res);
-    } catch (error) {
+    } catch (err) {
       res.writeHead(500, { "content-type": "text/plain" });
-      res.end((error instanceof Error && error.stack) || String(error));
+      res.end((err instanceof Error && err.stack) || String(err));
     }
   });
-  server.listen(port, host, () => {
-    console.log(`Darkmown dev server ready at http://${host}:${port}`);
-    console.log(`Live compiler watching site/ and src/`);
+
+  return new Promise((resolve) => {
+    server.listen(port, host, () => {
+      log(`Darkmown dev server ready at http://${host}:${port}`);
+      log(`Live compiler watching site/ and src/`);
+      resolve({
+        command: "dev",
+        server,
+        close: () => {
+          clearTimeout(timer);
+          for (const watcher of watchers) watcher.close();
+          for (const client of clients) client.end();
+          clients.clear();
+          return new Promise((done) => server.close(() => done()));
+        }
+      });
+    });
   });
-} else if (command === "serve") {
+}
+
+/**
+ * Start the static preview server for an existing `dist/`. Throws `CliError`
+ * when there is nothing built to serve.
+ * @param {{ cwd: string, log: typeof console.log, error: typeof console.error }} io
+ * @returns {Promise<{ command: "serve", server: import("node:http").Server, close: () => Promise<void> }>}
+ */
+function startPreviewServer({ cwd, log, error }) {
   const port = Number(process.env.PORT || 4173);
   const host = process.env.HOST || "127.0.0.1";
-  const distRoot = path.join(process.cwd(), "dist");
+  const distRoot = path.join(cwd, "dist");
   if (!fs.existsSync(distRoot)) {
-    console.error("No dist directory found. Run `darkmown build` first.");
-    process.exit(1);
+    error("No dist directory found. Run `darkmown build` first.");
+    throw new CliError("No dist directory found. Run `darkmown build` first.", { silent: true });
   }
-  http.createServer((req, res) => serve(distRoot, req.url || "/", res)).listen(port, host, () => {
-    console.log(`Darkmown preview of dist at http://${host}:${port}`);
+  const server = http.createServer((req, res) => serve(distRoot, req.url || "/", res));
+  return new Promise((resolve) => {
+    server.listen(port, host, () => {
+      log(`Darkmown preview of dist at http://${host}:${port}`);
+      resolve({
+        command: "serve",
+        server,
+        close: () => new Promise((done) => server.close(() => done()))
+      });
+    });
   });
-} else {
-  console.error(`Unknown command: ${command}`);
-  printHelp();
-  process.exit(1);
 }
 
 /**
@@ -165,8 +264,12 @@ function serveDev(distRoot, url, res) {
     return;
   }
   if (file.endsWith(".html")) {
+    // Read BEFORE writing headers: if the read throws (e.g. the path is a
+    // directory), the handler's catch can still send a clean 500 instead of
+    // failing to overwrite an already-sent 200.
+    const html = injectDevClient(fs.readFileSync(file, "utf8"));
     res.writeHead(200, { "content-type": "text/html" });
-    res.end(injectDevClient(fs.readFileSync(file, "utf8")));
+    res.end(html);
     return;
   }
   res.writeHead(200, { "content-type": contentType(file) });
@@ -183,18 +286,11 @@ function broadcast(clients, message) {
 }
 
 /**
- * Print a compile/CLI error as a single clean line and exit non-zero — no Node
- * stack trace. The thrown Error already carries the file path + corrective hint.
- * @param {unknown} error
- * @returns {never}
+ * The CLI help text. Returned (not printed) so `run` and tests share one source.
+ * @returns {string}
  */
-function failClean(error) {
-  console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
-  process.exit(1);
-}
-
-function printHelp() {
-  console.log(`Darkmown
+export function helpText() {
+  return `Darkmown
 
 Usage:
   darkmown init [dir]   Scaffold a new Darkmown project
@@ -210,15 +306,58 @@ Authoring:
   @loop x into item   Loop over JSON files, in-scope values, or :state lists
   *.skin              Colocated indentation-based CSS
   *.js                Colocated page behavior
-`);
+`;
 }
 
-
 /**
  * @param {string} relativeRoot
  * @returns {string}
  */
-function nextStep(relativeRoot) {
+export function nextStep(relativeRoot) {
   if (relativeRoot === ".") return "npm install && npm run dev";
   return `cd ${relativeRoot} && npm install && npm run dev`;
 }
+
+/**
+ * Binary entry point: read argv, dispatch, and map failures to a clean
+ * `✗`-prefixed line + exit code 1 — never a Node stack trace. The thrown Error
+ * already carries the file path + corrective hint.
+ * @returns {Promise<void>}
+ */
+async function main() {
+  try {
+    await run(process.argv.slice(2));
+  } catch (error) {
+    if (!(error instanceof CliError && error.silent)) {
+      // A compile error has a clear, file-pathed message — print just that.
+      console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Whether `entryArg` (typically `process.argv[1]`) points at THIS module — i.e.
+ * the binary is being executed, not imported by a test. npm installs the
+ * `darkmown` bin as a SYMLINK in node_modules/.bin, so the entry arg is the link
+ * path while `import.meta.url` resolves to the real file; comparing realpaths
+ * lets the binary still self-execute. Exported so the symlink/missing-path
+ * branches are unit-testable.
+ * @param {string | undefined} entryArg
+ * @returns {boolean}
+ */
+export function isEntryPoint(entryArg) {
+  if (!entryArg) return false;
+  if (entryArg === cliPath) return true;
+  try {
+    // Resolve symlinks on BOTH sides: npm's .bin/darkmown is a link to this file.
+    return fs.realpathSync(entryArg) === fs.realpathSync(cliPath);
+  } catch {
+    return false; // a non-existent entry path can never be this module
+  }
+}
+
+// Auto-run only when this file is the process entry point.
+if (isEntryPoint(process.argv[1])) {
+  main();
+}