@zvndev/darkmown 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.12.1 — 2026-06-18
+
+Release-hygiene and DX polish (post-0.12.0 smoke audit).
+
+- **Clean compile errors.** `darkmown build` prints a single `✗ <message>` line on a compile error instead of a raw Node.js stack trace (the dev rebuild log inherits the same clean output). The message still carries the file path and corrective hint.
+- **Bare `darkmown` prints help.** Running the command with no arguments shows usage instead of silently running a build.
+- **Social-share images.** A new `image:` frontmatter key sets `og:image` / `twitter:image` and upgrades the Twitter card to `summary_large_image`. The home page now ships an Open Graph card.
+- **`SECURITY.md` ships in the package** so the README's in-package security link resolves for npm consumers.
+- **Static assets documented.** README explains that non-page shelf files (`site/_/`) are copied to `/__wd/media/` (and `.json` to `/__wd/data/`).
+- **README badges** added (npm version, CI, provenance, license).
+
 ## 0.12.0 — 2026-06-18
 
 Security and deploy-hardening sprint.

package/README.md

@@ -1,5 +1,10 @@
 # Darkmown
 
+[![npm](https://img.shields.io/npm/v/@zvndev/darkmown)](https://www.npmjs.com/package/@zvndev/darkmown)
+[![CI](https://github.com/ZVN-DEV/darkmown/actions/workflows/ci.yml/badge.svg)](https://github.com/ZVN-DEV/darkmown/actions/workflows/ci.yml)
+[![provenance](https://img.shields.io/badge/npm-provenance-blue)](https://www.npmjs.com/package/@zvndev/darkmown)
+[![license](https://img.shields.io/npm/l/@zvndev/darkmown)](./LICENSE)
+
 **[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 ~4.7 KB gzipped, CI-enforced under 5 KB.
@@ -74,6 +79,17 @@ tags: [sales, revenue, "q1, q2"]
 - `@loop meta.tags into tag` iterates an array field at build time (stays static, zero-JS).
 - Arrays are inline flow only (`[a, b]`); quoted items keep internal commas (`"q1, q2"`). A value without a leading `[` stays a plain string.
 
+Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card).
+
+## Static assets
+
+Images, fonts, icons, and other non-page files live on the include shelf at `site/_/` and are copied into the build untouched:
+
+- Any non-`.md`/`.wd` file in `site/_/` → served at `/__wd/media/<path>` (e.g. `site/_/logo.svg` → `/__wd/media/logo.svg`).
+- `.json` files → served at `/__wd/data/<name>` (this is what `:fetch` reads).
+
+Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension. (Files dropped in `site/pages/` are treated as routes, not assets — put shareable assets on the shelf.)
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Supported versions
+
+Darkmown is pre-1.0. Only the latest published minor version receives security fixes.
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately via [GitHub Security Advisories](https://github.com/ZVN-DEV/darkmown/security/advisories/new). Do not open public issues for security reports.
+
+You can expect an initial response within 72 hours. If the report is accepted, a fix ships as the next patch release and the advisory is published after the fix is available.
+
+## Trust boundary / threat model
+
+Darkmown is a **trusted-author** static site generator. The threat model assumes you compile content you wrote yourself, the same way you trust your own source code — it does not assume the content is hostile. Within that boundary the guarantees below hold; three assumptions define the boundary itself:
+
+1. **Compile only trusted, author-written content.** Do not compile `.md`/`.wd` files you did not write — user-generated content, third-party docs, or form input — without applying your own sanitization first.
+2. **Raw HTML passes through by default.** `markdown-it` runs with `html: true`, so raw HTML in content is emitted verbatim. There is no built-in sanitizer, so a raw `<script>` or event-handler attribute in untrusted content would execute in the visitor's browser. A page can opt into strict mode with `html: false` frontmatter, which strips raw HTML.
+3. **`:fetch` has no URL allowlist, and reactive pages require `unsafe-eval`.** A `:fetch` URL is read directly from the page source, so requests go wherever the author wrote them. Reactive pages also need `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` expressions through `new Function`; a strict CSP without `unsafe-eval` breaks reactive pages (static pages are unaffected).
+
+This is the same trust posture as every Markdown SSG: the framework is safe for the trusted-author use case it targets, and unsafe content is the author's responsibility to sanitize before it reaches the compiler.
+
+## Security model
+
+Things Darkmown deliberately guards at compile time and runtime:
+
+- **No arbitrary JavaScript in content files.** Directive actions (`:button -> …`), `:computed` expressions, and `@loop … where` predicates compile through strict whitelisted grammars — only item paths, declared `:state`, numbers, and strings are allowed. Assignment, function calls, and unknown syntax are compile errors. Raw user content is never `eval`'d; what runs at runtime is the *validated* expression, compiled to the whitelisted grammar and executed via `new Function` (see `src/runtime.js`).
+- **Prototype-walk protection.** Path lookups (`{ a.b.c }`, computed expressions) reject `constructor`, `prototype`, and `__proto__` segments in both the compiler and the runtime.
+- **Include sandboxing.** `@include` and `@loop` data sources must resolve inside `site/pages` or `site/_`; traversal outside the site tree is a compile error, and include cycles are detected.
+- **Output escaping.** Interpolated values are HTML-escaped; state scripts escape `<` to prevent script-tag breakout.
+- **Static server path containment.** The dev/preview servers resolve requests strictly inside `dist`.
+
+## The biggest footgun: raw HTML passthrough
+
+Darkmown configures markdown-it with `html: true`, so **raw HTML in `.md`/`.wd` files is passed through verbatim** — by design, like every Markdown site generator. This is the single most important thing to understand about Darkmown's security model.
+
+- Treat all content files as **trusted input**, the same way you trust your own source code.
+- **Do not compile untrusted or user-submitted Markdown** (comments, form input, third-party docs) without sanitizing it first. Darkmown ships no built-in sanitizer; raw `<script>` and event-handler attributes in untrusted content would execute in the visitor's browser.
+- If you must render untrusted content, sanitize it (for example with a library like DOMPurify) before it reaches the compiler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -34,6 +34,7 @@
     "docs/spec-alignment.md",
     "AGENTS.md",
     "README.md",
+    "SECURITY.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

package/site/pages/index.wd

@@ -1,6 +1,7 @@
 ---
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
+image: https://darkmown.com/__wd/media/og.png
 ---
 
 @include /nav.wd

package/src/cli.js

@@ -10,7 +10,9 @@ import { initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
-const command = process.argv[2] || "build";
+// 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();
@@ -18,14 +20,24 @@ if (command === "help" || command === "--help" || command === "-h") {
   const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   console.log(pkg.version);
 } else if (command === "init") {
-  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)}`);
+  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);
+  }
 } else if (command === "build") {
-  const result = buildSite();
-  console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
+  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);
+  }
 } else if (command === "dev") {
   const port = Number(process.env.PORT || 5173);
   const host = process.env.HOST || "127.0.0.1";
@@ -170,6 +182,17 @@ function broadcast(clients, message) {
   for (const client of clients) client.write(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}
+ */
+function failClean(error) {
+  console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`Darkmown
 

package/src/compiler.js

@@ -110,13 +110,24 @@ export function compilePage(file, context) {
   const compiled = compileDocument(file, context);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
-  const descriptionTag = description
-    ? `\n  <meta name="description" content="${escapeHtml(description)}">
-  <meta property="og:title" content="${escapeHtml(title)}">
-  <meta property="og:description" content="${escapeHtml(description)}">
-  <meta property="og:type" content="website">
-  <meta name="twitter:card" content="summary">`
-    : "";
+  // Optional `image:` frontmatter sets the social-share preview (absolute URL).
+  const image = typeof compiled.meta.image === "string" ? compiled.meta.image : "";
+  /** @type {string[]} */
+  const social = [];
+  if (description) social.push(`<meta name="description" content="${escapeHtml(description)}">`);
+  if (description || image) {
+    social.push(`<meta property="og:title" content="${escapeHtml(title)}">`);
+    if (description) social.push(`<meta property="og:description" content="${escapeHtml(description)}">`);
+    social.push(`<meta property="og:type" content="website">`);
+  }
+  if (image) {
+    social.push(`<meta property="og:image" content="${escapeHtml(image)}">`);
+    social.push(`<meta name="twitter:image" content="${escapeHtml(image)}">`);
+  }
+  if (description || image) {
+    social.push(`<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}">`);
+  }
+  const descriptionTag = social.length ? `\n  ${social.join("\n  ")}` : "";
   const favicon = "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2032%2032'%3E%3Crect%20width='32'%20height='32'%20rx='6'%20fill='%2318221d'/%3E%3Ctext%20x='16'%20y='23'%20text-anchor='middle'%20font-family='Georgia,serif'%20font-size='19'%20font-weight='bold'%20fill='%23f7f3ea'%3ED%3C/text%3E%3C/svg%3E";
   const cssLinks = [...compiled.assets.skins].map((href) => `<link rel="stylesheet" href="${href}">`).join("\n");
   const scriptSrcs = compiled.assets.runtime ? ["/__wd/runtime.js", ...compiled.assets.scripts] : [...compiled.assets.scripts];