vowel 0.7.1-beta.0 → 0.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vowel",
   "type": "module",
-  "version": "0.7.1-beta.0",
+  "version": "0.7.3",
   "engines": {
     "node": ">=26"
   },
@@ -32,26 +32,20 @@
     "@bomb.sh/tab": "^0.0.15",
     "@clack/prompts": "^1.4.0",
     "@jsdevtools/rehype-toc": "^3.0.2",
-    "autoprefixer": "^10.4.27",
-    "colorhorse": "^0.3.1",
-    "cssnano": "^7.1.4",
+    "colorhorse": "^0.5.0",
     "emojilib": "^4.0.3",
-    "encoding-sniffer": "^1.0.2",
     "fast-xml-parser": "^5.3.6",
-    "faye-websocket": "^0.11.4",
     "github-slugger": "^2.0.0",
     "hast-util-from-html": "^2.0.3",
+    "hast-util-to-html": "^9.0.5",
     "hast-util-to-string": "^3.0.1",
     "hast-util-to-text": "^4.0.2",
     "hastscript": "^9.0.1",
-    "highlight.js": "^11.12.0",
-    "js-yaml": "^4.1.0",
     "lightningcss": "^1.33.0",
     "lowlight": "^3.3.0",
-    "mdast": "^2.3.2",
-    "mdast-normalize-headings": "^4.0.0",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",
+    "mdast-util-gfm-footnote": "^2.1.0",
     "mdast-util-gfm-strikethrough": "^2.0.0",
     "mdast-util-gfm-table": "^2.0.0",
     "mdast-util-gfm-task-list-item": "^2.0.0",
@@ -61,42 +55,21 @@
     "mdast-util-to-string": "^4.0.0",
     "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm-footnote": "^2.1.0",
+    "micromark-extension-gfm-strikethrough": "^2.1.0",
     "micromark-extension-gfm-table": "^2.1.1",
-    "micromark-extension-gfm-task-list-item": "^2.1.0",
     "micromark-extension-highlight-mark": "^1.2.0",
-    "postcss": "^8.5.9",
-    "rehype": "^13.0.2",
-    "rehype-document": "^7.0.3",
-    "rehype-github-alert": "^1.0.0",
-    "rehype-parse": "^9.0.1",
     "rehype-preset-minify": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
-    "remark": "^15.0.1",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-html": "^16.0.1",
-    "remark-parse": "^11.0.0",
-    "remark-rehype": "^11.1.2",
     "rollup-plugin-import-css": "^4.2.1",
     "sharp": "^0.35.3",
     "svedit": "^0.14.0",
     "unified": "^11.0.5",
-    "unist-util-find": "^3.0.0",
-    "unist-util-is": "^6.0.0",
-    "unist-util-position": "5.0.0",
-    "unist-util-remove": "^4.0.0",
-    "unist-util-stringify-position": "^4.0.0",
     "unist-util-visit": "^5.0.0",
-    "unist-util-visit-parents": "^6.0.0",
     "unpic": "^4.2.2",
-    "url-metadata": "^5.4.1",
-    "votive": "0.5.0-beta.0",
-    "xast-util-sitemap": "^2.0.0",
-    "xast-util-to-xml": "^4.0.0",
+    "votive": "0.5",
     "xml": "^1.0.1",
-    "yaml": "^2.8.2",
-    "yamljs": "^0.3.0"
+    "yaml": "^2.8.2"
   },
   "files": [
     "bin.js",
@@ -104,6 +77,7 @@
     "config.js",
     "extractDate.js",
     "index.js",
+    "pathDate.js",
     "secretPaths.js",
     "systemPaths.js",
     "utils.js",

package/pathDate.js

@@ -0,0 +1,69 @@
+import path from "node:path"
+import { monthIndex } from "./extractDate.js"
+
+// Strict on purpose, and separate from extractDate's pattern: that one is
+// unanchored and reads day-first orders, so on "2023/03/2023-03-24" it
+// matches "2023/03/2023". A path is a guess the author never wrote as a
+// date, so only the year-month-day order counts, each part a whole
+// segment.
+const YEAR = /^\d{4}$/
+const MONTH = /^(?:\d{1,2}|jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t|tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)$/i
+const DAY = /^\d{1,2}$/
+const NAME_PREFIX = /^(\d{4})-(\d{1,2})-(\d{1,2})(?!\d)/
+
+/**
+ * @param {string} year
+ * @param {string} month - a number or a month name
+ * @param {string} day
+ */
+function calendarDate(year, month, day) {
+  const yearNumber = Number(year)
+  const monthNumber = monthIndex(month)
+  const dayNumber = Number(day)
+  const date = new Date(Date.UTC(yearNumber, monthNumber, dayNumber))
+
+  // Date.UTC rolls 30 February into March and month 13 into next year,
+  // and maps years 0-99 to 1900-1999; any of those is not the date the
+  // path spelled.
+  const rolled =
+    date.getUTCFullYear() !== yearNumber ||
+    date.getUTCMonth() !== monthNumber ||
+    date.getUTCDate() !== dayNumber
+
+  if (rolled) return
+  return date
+}
+
+/**
+ * @param {string} year
+ * @param {string} month
+ * @param {string} day
+ */
+function segmentsDate(year, month, day) {
+  const isDate = YEAR.test(year) && MONTH.test(month) && DAY.test(day)
+  if (!isDate) return
+  return calendarDate(year, month, day)
+}
+
+/**
+ * The date a source path spells, or undefined: a `YYYY-MM-DD` filename
+ * prefix (`blog/2024/2024-11-03-sixty.md`), else a year, month and day in
+ * neighbouring segments (`2023/04/07/hello-world.md`,
+ * `journal/2024/april/1.md`), the deepest run winning. A secret segment's
+ * salt should already be stripped (displayPath).
+ * @param {string} sourcePath - project-relative
+ */
+function pathDate(sourcePath) {
+  const { dir, name } = path.parse(sourcePath)
+
+  const prefix = NAME_PREFIX.exec(name)
+  const nameDate = prefix ? calendarDate(prefix[1], prefix[2], prefix[3]) : undefined
+  if (nameDate) return nameDate
+
+  const segments = [...dir.split(path.sep), name]
+  const dates = segments.slice(0, -2).map((year, index) => segmentsDate(year, segments[index + 1], segments[index + 2]))
+  return dates.findLast(Boolean)
+}
+
+export default pathDate
+export { pathDate }

package/plugins/assets/index.js

@@ -20,7 +20,7 @@ import path from "node:path"
  * to be there; adding an extension is adding it here.
  */
 
-const EXTENSIONS = [".mp4", ".webm", ".csv", ".json", ".pdf"]
+const EXTENSIONS = [".mp4", ".webm", ".csv", ".json", ".pdf", ".ico"]
 
 /** 25 MiB: Cloudflare Pages' per-file limit. */
 const DEFAULT_SIZE_LIMIT = 25 * 1024 * 1024

package/plugins/atproto/body.js

@@ -113,7 +113,9 @@ function phrase(node, base) {
   }
   if (tag === "picture") {
     const img = (node.children ?? []).find(child => is(child, "img"))
-    const src = node.properties?.dataOriginal ?? img?.properties?.src
+    // The <img>'s src is the largest derivative in the image's own
+    // format; the original is not published (plugins/images).
+    const src = img?.properties?.src
     return src ? [{ type: "image", url: absolute(String(src), base), alt: String(img?.properties?.alt ?? "") }] : []
   }
   if (tag === "a") {

package/plugins/atproto/index.js

@@ -1,6 +1,5 @@
 import path from "node:path"
-import { lexiconFor, publicationURI, recordURI, siteOrigin } from "./record.js"
-import { validNSID } from "./lexicons.js"
+import { publicationURI, siteOrigin, validDID } from "./record.js"
 import { publishToAtproto } from "./publish.js"
 import { saveAppPassword } from "./password.js"
 
@@ -21,8 +20,9 @@ import { saveAppPassword } from "./password.js"
  * pastes the DID from their account settings. Resolving it from a handle
  * is a later phase, through readURL like any other fetch.
  *
- * Phase two: a page under an `atproto_lexicon:` gets an AT-URI, computed
- * by `transformFile` with no network (record.js). Any published lexicon
+ * Phase two: a page under an `atproto_lexicon:` has an AT-URI, a function
+ * of the page and its settings with no network (record.js's
+ * `pageRecordURI`, worked out at write and at publish). Any published lexicon
  * will do: vowel bundles none. Publishing is a command,
  * `atproto-publish` (publish.js), which fetches each lexicon, fits the
  * page to it (mapper.js) and sends what changed. A
@@ -38,11 +38,6 @@ import { saveAppPassword } from "./password.js"
 const WELL_KNOWN = path.join(".well-known", "atproto-did")
 const WELL_KNOWN_PUBLICATION = path.join(".well-known", "site.standard.publication")
 
-/** A DID is `did:<method>:<id>`; that is all this checks. */
-function validDID(value) {
-  return typeof value === "string" && /^did:[a-z]+:[A-Za-z0-9._:%-]+$/.test(value)
-}
-
 /**
  * The account, from the nearest settings.md that names one. The atproto
  * settings are flat, `atproto_did` / `atproto_lexicon` / `atproto_pds`,
@@ -54,35 +49,6 @@ function atprotoDID(settings) {
   return settings.lastNonNull("fm_atproto_did")
 }
 
-/**
- * The page's AT-URI, stored as metadata for the html plugin's link and
- * the publish command. Runs once per read of the page and reaches no
- * network, so it can't know whether the page fits its lexicon - the
- * publish command finds that out. A lexicon name that isn't an NSID is
- * warned about here.
- *
- * Not for a page with `status: hidden`, which is listed nowhere, nor for
- * one that isn't written (`html_file: false`) - except `status: deleted`,
- * which is kept unwritten precisely so publish can delete its record.
- */
-function transformFile(target, { settings, config }) {
-  const status = target.metadata.fm_status
-  if (status === "hidden") return undefined
-  if (target.write === false && status !== "deleted") return undefined
-  const did = atprotoDID(settings)
-  if (!validDID(did)) return undefined
-  const origin = siteOrigin(settings.lastNonNull("fm_domain"))
-  if (!origin) return undefined
-
-  const lexicon = lexiconFor(target, settings)
-  if (!lexicon) return undefined
-  if (!validNSID(lexicon)) {
-    config.log("warn", `${target.path}: atproto_lexicon "${lexicon}" is not a lexicon name (an NSID, like app.bsky.feed.post)`)
-    return undefined
-  }
-  return { metadata: { atUri: recordURI(did, lexicon, origin, target.metadata.prettyURL) } }
-}
-
 /** @type {Votive.ProcessorStubs} */
 function createStubs({ settings }) {
   const did = atprotoDID(settings)
@@ -118,16 +84,10 @@ const wellKnownProcessor = {
   writeFile: (target) => ({ data: target.data })
 }
 
-const recordProcessor = {
-  extensions: [".html"],
-  format: "text",
-  transformFile
-}
-
 /** @type {Votive.VotivePlugin} */
 const vowelAtprotoPlugin = {
   name: "vowel-atproto",
-  processors: [wellKnownProcessor, recordProcessor],
+  processors: [wellKnownProcessor],
   commands: {
     "atproto-publish": publishToAtproto,
     "atproto-password": saveAppPassword

package/plugins/atproto/publish.js

@@ -7,10 +7,12 @@ import votive from "votive"
 import { systemDirectoryFor } from "../../systemPaths.js"
 import { EXPECTED } from "../markdown/frontmatter.js"
 import { contentSection } from "../xml/entryContent.js"
-import { PUBLICATION, siteOrigin, publicationURI } from "./record.js"
+import { PUBLICATION, siteOrigin, publicationURI, pageRecordURI } from "./record.js"
 import { createLexiconResolver, resolvePDS } from "./lexicons.js"
 import { mapRecord } from "./mapper.js"
 import { markdownBody, richTextBody } from "./body.js"
+import { imageURL } from "../html/image.js"
+import { imageSizes } from "../../utils.js"
 
 /**
  * `vowel --command atproto-publish`: make the account's records match the
@@ -232,12 +234,44 @@ function pageFor(target, pageURL) {
   }
 }
 
+/**
+ * The folder whose settings a page reads: the page as a folder -
+ * `blog/post.html` → `blog/post` - which is what votive hands a write
+ * (`pageSettingsFolder` in votive's lib/utils, not exported), so publish
+ * sees each page's lexicon exactly as its write did. `index.html` is
+ * `/index` there, and here.
+ * @param {string} targetPath
+ */
+function pageSettingsFolder(targetPath) {
+  const segments = targetPath.split("/").filter(Boolean)
+  const folder = path.relative("", [...segments.slice(0, -1), ""].join(path.sep))
+  return folder + path.sep + path.parse(targetPath).name
+}
+
+/**
+ * Every page under a lexicon, with its AT-URI: the author's own pages -
+ * a generated one (a tag page, a folder index, the default home or 404)
+ * is a stub, and inherits a folder's lexicon without being anything to
+ * publish.
+ * @param {any} database - a built site's
+ * @returns {{ target: any, uri: string }[]}
+ */
+function recordPages(database) {
+  const stubs = new Set(database.source.getStubs().map(row => row.path))
+  return database.target.getAll()
+    .filter(target => target.extension === ".html" && !stubs.has(target.source))
+    .map(target => ({ target, uri: pageRecordURI(target, database.setting.getByFolder(pageSettingsFolder(target.path))).uri }))
+    .filter(page => typeof page.uri === "string")
+}
+
 /**
  * What the site should hold: every page under a lexicon - its AT-URI,
  * its status, and what mapper.js reads - the site's own settings, and
  * the publication's name, description and icon. The icon is read from
  * the build's output - it is a URL path from the root (frontmatter.js
- * resolves it), which is where the output has it. Built into a scratch
+ * resolves it), which is where the output has it; a png or jpeg is read
+ * from its largest derivative, since the original is not published
+ * (plugins/images). Built into a scratch
  * folder that is removed afterwards.
  * @param {import("votive").VotiveConfig} config
  */
@@ -257,13 +291,8 @@ async function collectPages(config) {
       const pds = root.lastNonNull("fm_atproto_pds")
       const domain = root.lastNonNull("fm_domain")
       const origin = siteOrigin(domain)
-      // Only the author's own pages: a generated one - a tag page, a
-      // folder index, the default home or 404 - is a stub, and inherits a
-      // folder's lexicon without being anything to publish.
-      const stubs = new Set(site.database.source.getStubs().map(row => row.path))
-      const targets = site.database.target.getAll()
-      const pages = targets.filter(target => typeof target.metadata.atUri === "string" && !stubs.has(target.source)).map(target => {
-        const [, , account, collection, rkey] = target.metadata.atUri.split("/")
+      const pages = recordPages(site.database).map(({ target, uri }) => {
+        const [, , account, collection, rkey] = uri.split("/")
         const pageURL = new URL(target.metadata.prettyURL, origin).href
         const contentLexicon = site.database.setting.getByFolder(target.dir).lastNonNull("fm_atproto_content")
         return {
@@ -281,7 +310,9 @@ async function collectPages(config) {
       const home = site.database.target.get("index.html")
       const name = root.raw("fm_name")?.[0]?.at(-1) ?? (home?.source ? home.metadata.title : undefined)
       const iconPath = settings.icon ?? root.lastNonNull("logo")
-      const icon = iconPath ? await readIcon(path.join(scratch, "output"), iconPath) : undefined
+      // imageURL asks an api for the target; the database answers the same.
+      const builtIcon = imageURL(iconPath, { target: (targetPath) => site.database.target.get(targetPath) }, imageSizes.at(-1))
+      const icon = builtIcon ? await readIcon(path.join(scratch, "output"), builtIcon) : undefined
       const publication = { name, description: settings.description, iconPath, icon }
       return { did, pds, domain, pages, publication }
     } finally {
@@ -468,4 +499,4 @@ async function publishToAtproto(payload, { config, notify }) {
   return summary
 }
 
-export { publishToAtproto, planWrites, planPublication, sameRecord, resolvePDS, blobCID, xrpc, passwordFile }
+export { publishToAtproto, recordPages, pageSettingsFolder, planWrites, planPublication, sameRecord, resolvePDS, blobCID, xrpc, passwordFile }

package/plugins/atproto/record.js

@@ -1,11 +1,22 @@
 import { MARKER } from "../../secretPaths.js"
 import createRkey from "./rkey.js"
+import { validNSID } from "./lexicons.js"
 
 /**
  * Which pages become records, and where each record lives. No network,
- * and no lexicon: the build decides a page's lexicon and its AT-URI; the
- * record itself is made at publish (publish.js), once the lexicon has
- * been fetched (lexicons.js) and the page fitted to it (mapper.js).
+ * and no lexicon: a page's lexicon and AT-URI are a function of the page
+ * and its settings (`pageRecordURI`), worked out wherever they're needed -
+ * the html plugin's write, for standard.site's `<link>`, and
+ * atproto-publish. The record itself is made at publish (publish.js),
+ * once the lexicon has been fetched (lexicons.js) and the page fitted to
+ * it (mapper.js).
+ *
+ * At write, not in a transform: a transform runs only when its page is
+ * read, so adding `atproto_did` or a lexicon to a settings.md changed
+ * nothing for pages already built - not even after a restart, since the
+ * database persists (tasks/1-proposed/transform-reruns-on-stale.md).
+ * Settings read at write are tracked, so a change re-renders the pages
+ * it reaches.
  *
  * `site.standard.publication` is the one lexicon named here: standard.site
  * defines a document's `site` as its publication's AT-URI, and vowel
@@ -75,6 +86,38 @@ function publicationURI(did, origin) {
   return `at://${did}/${PUBLICATION}/${createRkey(origin)}`
 }
 
+/** A DID is `did:<method>:<id>`; that is all this checks. @param {unknown} value */
+function validDID(value) {
+  return typeof value === "string" && /^did:[a-z]+:[A-Za-z0-9._:%-]+$/.test(value)
+}
+
+/**
+ * The page's AT-URI, from the page and its settings - the page-as-folder
+ * view a write gets (`blog/post.html` reads `""`, `blog`, `blog/post`).
+ * None for a page with `status: hidden`, which is listed nowhere, nor for
+ * one that isn't written (`html_file: false`) - except `status: deleted`,
+ * which is kept unwritten precisely so publish can delete its record.
+ * None without an account, a `domain` (the key is made from the page's
+ * url) or a lexicon. A lexicon name that isn't an NSID comes back as a
+ * warning; whether the page fits its lexicon is publish's question.
+ * @param {{ source?: string, write?: boolean, metadata: Record<string, any> }} target
+ * @param {any} settings
+ * @returns {{ uri?: string, warning?: string }}
+ */
+function pageRecordURI(target, settings) {
+  const status = target.metadata.fm_status
+  if (status === "hidden") return {}
+  if (target.write === false && status !== "deleted") return {}
+  const did = settings.lastNonNull("fm_atproto_did")
+  if (!validDID(did)) return {}
+  const origin = siteOrigin(settings.lastNonNull("fm_domain"))
+  if (!origin) return {}
+  const lexicon = lexiconFor(target, settings)
+  if (!lexicon) return {}
+  if (!validNSID(lexicon)) return { warning: `atproto_lexicon "${lexicon}" is not a lexicon name (an NSID, like app.bsky.feed.post)` }
+  return { uri: recordURI(did, lexicon, origin, target.metadata.prettyURL) }
+}
+
 /**
  * The page's AT-URI: the account, the lexicon, and a key derived from
  * the page's canonical URL - origin and path - and frozen (rkey.js).
@@ -87,4 +130,4 @@ function recordURI(did, lexicon, origin, prettyURL) {
   return `at://${did}/${lexicon}/${createRkey(new URL(prettyURL, origin).href)}`
 }
 
-export { PUBLICATION, lexiconFor, siteOrigin, publicationURI, recordURI }
+export { PUBLICATION, validDID, lexiconFor, siteOrigin, publicationURI, recordURI, pageRecordURI }

package/plugins/deploy-cloudflare/index.js

@@ -66,7 +66,10 @@ async function deployToCloudflarePages(payload, { config, notify }) {
     proc.stdout.on("data", chunk => notify({ status: "progress", message: chunk.toString() }))
     proc.stderr.on("data", chunk => notify({ status: "progress", message: chunk.toString() }))
 
-    proc.on("error", reject) // e.g. wrangler isn't installed
+    proc.on("error", error => {
+      if (error.code !== "ENOENT") return reject(error)
+      reject(new Error("wrangler isn't installed, and deploying to Cloudflare Pages needs it. Install it with `npm install -g wrangler`, then deploy again."))
+    })
     proc.on("exit", code => {
       if (code === 0) resolve({ deployed: true, projectName })
       else reject(new Error(`wrangler exited with code ${code}`))

package/plugins/export/index.js

@@ -0,0 +1,131 @@
+import { cp, readdir, stat } from "node:fs/promises"
+import { realpathSync } from "node:fs"
+import path from "node:path"
+import votive from "votive"
+import { systemDirectoryFor } from "../../systemPaths.js"
+
+/** @import * as Votive from "votive" */
+
+/**
+ * `vowel export <folder>`: build the site and copy it to a folder of
+ * your choosing - to upload anywhere, archive, or hand to someone. The
+ * same command a desktop "Export" button would run
+ * (`vowel --command export --payload '{"path": "…"}'`).
+ *
+ * It copies the output folder whole. If the output ever holds files it
+ * shouldn't, that is the output's problem to fix, not the export's.
+ *
+ * **Where it won't write**, checked before anything is built, on real
+ * paths so a symlink can't hide the answer:
+ * - inside the project: the next build would read the export as content,
+ *   and each export would nest inside the next
+ * - a folder that contains the project, or is it
+ * - vowel's own system folder (the output, the database, the cache)
+ * - a folder that isn't empty: nothing an export writes should mix with,
+ *   or silently replace, what's already there
+ *
+ * A destination that doesn't exist yet is created.
+ */
+
+/**
+ * `child` is `parent` or somewhere inside it.
+ * @param {string} child
+ * @param {string} parent
+ */
+function within(child, parent) {
+  const relative = path.relative(parent, child)
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
+}
+
+/**
+ * A path made real as far as it exists: the deepest existing ancestor
+ * through realpath (symlinks resolved, and on a case-insensitive disk
+ * its true case), then the segments that don't exist yet.
+ * @param {string} absolute
+ * @returns {string}
+ */
+function realAsFarAsItExists(absolute) {
+  try {
+    return realpathSync.native(absolute)
+  } catch {
+    const parent = path.dirname(absolute)
+    if (parent === absolute) return absolute
+    return path.join(realAsFarAsItExists(parent), path.basename(absolute))
+  }
+}
+
+/**
+ * Where an export may go, or why it may not, as a sentence. Checks the
+ * places only; whether the folder is empty is `checkEmpty`'s.
+ * @param {string} destination - as given; relative to the working directory
+ * @param {{ sourceFolder: string, targetFolder: string }} config
+ * @returns {{ path: string } | { refused: string }}
+ */
+function checkDestination(destination, config) {
+  if (typeof destination !== "string" || !destination.trim()) {
+    return { refused: "say where to export to, e.g. `vowel export ../my-site`" }
+  }
+  const real = realAsFarAsItExists(path.resolve(destination))
+  const source = realAsFarAsItExists(config.sourceFolder)
+  const system = realAsFarAsItExists(systemDirectoryFor(config.sourceFolder))
+  const output = realAsFarAsItExists(config.targetFolder)
+
+  if (within(real, source)) {
+    return { refused: `${destination} is inside the project (${source}); the next build would read the export as part of the site. Export somewhere outside it.` }
+  }
+  if (within(source, real)) {
+    return { refused: `${destination} contains the project (${source}). Export to a folder of its own.` }
+  }
+  if (within(real, system) || within(real, output) || within(output, real)) {
+    return { refused: `${destination} is where vowel keeps its own build (${system}). Export somewhere else.` }
+  }
+  return { path: real }
+}
+
+/**
+ * @param {string} folder - real, absolute
+ * @param {string} destination - as given, for the message
+ * @returns {Promise<string | undefined>} why it can't be used, if it can't
+ */
+async function checkEmpty(folder, destination) {
+  const info = await stat(folder).catch(() => undefined)
+  if (!info) return undefined
+  if (!info.isDirectory()) return `${destination} is a file, not a folder.`
+  const entries = await readdir(folder)
+  if (entries.length) return `${destination} isn't empty. Export to a new or empty folder.`
+  return undefined
+}
+
+/**
+ * @param {{ path?: string } | undefined} payload
+ * @param {{ config: Votive.VotiveConfig, notify: (message: object) => void }} context
+ */
+async function exportSite(payload, { config, notify }) {
+  const checked = checkDestination(payload?.path, config)
+  if ("refused" in checked) throw new Error(`export: ${checked.refused}`)
+  const notEmpty = await checkEmpty(checked.path, payload.path)
+  if (notEmpty) throw new Error(`export: ${notEmpty}`)
+
+  notify({ status: "progress", message: "Building..." })
+  // As deploy does: everything finished, deferred work (image
+  // derivatives, link previews) included, and the database closed.
+  const site = await votive({ ...config, verbose: false })
+  await (await site.build()).deferred
+  await site.close()
+
+  notify({ status: "progress", message: `Copying to ${checked.path}...` })
+  await cp(config.targetFolder, checked.path, { recursive: true })
+  const files = await readdir(checked.path, { recursive: true, withFileTypes: true })
+  const count = files.filter(entry => entry.isFile()).length
+  notify({ status: "done", message: `Exported ${count} files to ${checked.path}` })
+  return { exported: checked.path, files: count }
+}
+
+/** @type {Votive.VotivePlugin} */
+const vowelExportPlugin = {
+  name: "vowel-export",
+  commands: { export: exportSite }
+}
+
+export default vowelExportPlugin
+export { exportSite, checkDestination, within }