vowel 0.6.3 → 0.7.0-beta.0

package/README.md

@@ -3,12 +3,17 @@
 *Markdown websites in milliseconds*
 
 - Bundled with [Votive](https://github.com/samlfair/votive)
-- Served with [Voot](https://github.com/samlfair/voot)
+- Served with [Votive](https://github.com/samlfair/votive)'s dev server
 
 See the docs: [vowel.cc](https://vowel.cc).
 
 ## Roadmap
 
+### Priorities
+
+- [ ] Create CONTRIBUTING.md
+- [ ] 
+
 ### Launch checklist
 
 - [x] CLI
@@ -17,14 +22,15 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [x] Route patterns
 - [x] Post list metadata
 - [.] Transaction management
+- [ ] Default 404 pages
 
 - [.] Fixes
   - [x] Global nav sublinks
   - [x] Hot reload
-  - [.] Explicit asset handling
+  - [x] Explicit asset handling
   - [.] Change "job" to "resources"
     - [.] ReadResource types
-  - [.] Processor utilities param
+  - [x] Processor utilities param
   - [.] Delete old SQLite logic
   - [.] Make metadata explicit in SQLiteTarget type
   - [x] Add SQLite begin/commit logic
@@ -35,12 +41,12 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [x] Homepage in global nav
   - [x] Metadata in header
   - [x] Page list sort
-  - [.] Limit in sort
+  - [x] Limit in sort
 - [x] Metafiles
   - [x] Robots.txt
   - [x] Sitemap.xml
   - [x] RSS
-  - [ ] 404.html (just make 404.md)
+  - [x] 404.html (just make 404.md)
 - [ ] Markup
   - [x] Image as figure
   - [x] Admonitions
@@ -49,10 +55,11 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [ ] Mermaid
   - [x] Slogan
   - [x] TOC
+  - [x] ==mark==
 - [ ] Non-urgent fixes / improvements
   - [ ] Compare metadata on file update
   - [x] Prune/cleanup step
-  - [ ] Dependency type (file, settings, folder)
+  - [x] Dependency type (file, settings, folder)
 - [ ] New systems
   - [x] Tags
   - [ ] External links
@@ -68,7 +75,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] GetMany "extension" filter
 - [ ] Delete settings logic
 - [ ] Update settings logic
-- [ ] Logical operators for filters
+- [x] Logical operators for filters
 - [ ] Customize menus
 - [ ] More file handling plugins
   - [ ] Fonts
@@ -91,21 +98,20 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [ ] Styles
     - [x] .css
     - [x] Bundling
-  - [ ] PDFs
-  - [ ] Videos
-  - [ ] Arbitrary data
+  - [x] PDFs
+  - [x] Videos
+  - [x] Arbitrary data
 - [x] Add homepage to global nav
 - [x] Page lists
 - [x] Dates
 - [x] robots.txt
 - [x] sitemap.xml
-- [ ] 404.html
+- [x] 404.html
 - [ ] Better URL normalization (see notes)
 - [x] Name casing
 - [x] TUI
   - [x] Create settings.md
     - [x] Site title
-    - [x] Domain
     - [ ] Webmentions
     - [x] Logo
     - [x] Wordmark
@@ -121,7 +127,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [x] Custom CSS
   - [x] styles.css
   - [ ] Any CSS file
-- [ ] Tags
+- [x] Tags
 - [ ] Date format settings
 - [ ] ::mark::
 - [x] Infer images
@@ -136,7 +142,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] Handle external links
 - [x] Admonitions
 - [ ] Use hgroup for site title, page title, etc
-- [ ] Images as `<figure>`
+- [x] Images as `<figure>`
 - [ ] Hidden routes
 - [ ] Frontmatter settings
   - [ ] HTML
@@ -156,8 +162,8 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] Image optimization (unpic)
 - [ ] [SVG by mask](https://pqina.nl/blog/set-svg-background-image-fill-color/) and [CSS icons](https://antfu.me/posts/icons-in-pure-css)
 - [ ] WYSIWYG editor
-- [ ] Better signals
-  - [ ] File-written callback
+- [x] Better signals
+  - [x] File-written callback
 - [ ] Themes
 - [ ] Deploy
   - [ ] Cloudflare pages
@@ -173,7 +179,7 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [ ] Image
   - [ ] URL
   - [ ] Date
-- [ ] TOC
+- [x] TOC
 - [ ] Versioning/publishing script
 - [ ] Verify all element types from Obsidian
 - [ ] Order/position/kanban

package/bin.js

@@ -6,7 +6,12 @@ import { parse } from "@bomb.sh/args"
 import t from "@bomb.sh/tab"
 import votive from "votive"
 import { styleText } from "node:util"
-import { config } from "./config.js"
+import { createConfig } from "./config.js"
+
+// The CLI's own boundary: cwd is the project folder by convention (you
+// `cd` into your blog and run `vowel`), so "." is the right default here
+// specifically - see createConfig's own doc comment.
+const config = createConfig(".")
 
 /** @param {number} ms */
 function wait(ms) {
@@ -14,27 +19,37 @@ function wait(ms) {
 }
 
 import init from "./index.js"
-
-/** @param {boolean} verbose */
-async function removeCache(verbose) {
+import { shouldClear } from "./cli.js"
+
+/**
+ * Discards the build database. Only under --clear (alias --reset): an
+ * ordinary launch is a warm start, reusing the database and the output,
+ * so a second launch on an unchanged site has nothing to do. The wipe on
+ * every launch was a development convenience, and it hid the on-disk
+ * database path from the CLI entirely.
+ * @param {boolean} verbose
+ */
+async function removeDatabase(verbose) {
   try {
-    await fs.rm("./.votive.db")
-    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "cache cleared")}`)
+    await fs.rm(config.databasePath)
+    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "database cleared")}`)
   } catch (e) {
-    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no database cache found")}`)
+    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no database found")}`)
   }
 }
 
 /** @param {boolean} verbose */
-async function removeDB(verbose) {
+async function removeOutput(verbose) {
   try {
-    await fs.rm("./output", { recursive: true, force: true })
+    await fs.rm(config.targetFolder, { recursive: true, force: true })
     if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "output cleared")}`)
   } catch (e) {
-    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no output cache found")}`)
+    if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no output found")}`)
   }
 }
 
+
+
 async function exists(filePath) {
   try {
     await fs.stat(filePath)
@@ -74,21 +89,12 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 
       box(`Change these configurations by editing 'settings.md'.`)
 
-      const websiteTitle = await text({
-        message: "Website title",
+      const websiteName = await text({
+        message: "Website name",
         placeholder: "My Cool Website"
       })
 
-      frontmatter.push(`title: ${websiteTitle}`)
-
-      const tagline = await text({
-        message: "Website tagline (leave empty to skip)",
-        placeholder: "All the news that's fit to blog"
-      })
-
-      if (tagline) {
-        frontmatter.push(`tagline: ${tagline}`)
-      }
+      frontmatter.push(`name: ${websiteName}`)
 
       box(`Vowel comes loaded with themes. You can override these themes by writing styles in a 'styles.css' file at the root of your project.`)
 
@@ -150,6 +156,12 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
         message: "Generate homepage"
       })
 
+      // A tagline is a page's; the homepage's is the site's hero.
+      const tagline = await text({
+        message: "Homepage tagline (leave empty to skip)",
+        placeholder: "All the news that's fit to blog"
+      })
+
       const spin = spinner()
 
       spin.start('Setting up')
@@ -167,7 +179,8 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
       const homeExists = await exists("home.md")
 
       if (!homeExists) {
-        await fs.writeFile("home.md", `# Home\n\nWelcome home!`, "utf-8")
+        const homeFrontmatter = tagline ? `---\ntagline: ${tagline}\n---\n` : ""
+        await fs.writeFile("home.md", `${homeFrontmatter}# Home\n\nWelcome home!`, "utf-8")
       }
 
       spin.clear()
@@ -190,23 +203,67 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 }
 
 
+/**
+ * Runs one registered command directly and exits - no dev server, no
+ * wizard, no cache-wiping. Reuses the exact handler a live "Publish"
+ * button would trigger over WS (see votive's runCommand/handleCommand) -
+ * this is just the other invocation path for the same registered
+ * function, meant for CI/automated use (e.g. `vowel --command deploy`).
+ * @param {string} name
+ * @param {string} [payloadJSON]
+ */
+async function runCLICommand(name, payloadJSON) {
+  const { runCommand } = await import("votive")
+
+  let payload
+  try {
+    payload = payloadJSON ? JSON.parse(payloadJSON) : undefined
+  } catch (e) {
+    console.error(`--payload must be valid JSON: ${e.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  try {
+    const data = await runCommand(config, name, payload, message => {
+      console.info(message?.message ?? message)
+    })
+    if (data !== undefined) console.info(JSON.stringify(data))
+  } catch (e) {
+    console.error(e?.message || e)
+    process.exitCode = 1
+  }
+}
+
 async function main() {
   const args = parse(process.argv.slice(2))
 
-  const dbExists = await exists(".votive.db")
+  if (args.command) {
+    await runCLICommand(args.command, args.payload)
+    return
+  }
+
+  const dbExists = await exists(config.databasePath)
 
-  await removeCache(args.logging === "verbose")
-  await removeDB(args.logging === "verbose")
-  await fs.mkdir(config.destinationFolder, { recursive: true })
+  if (shouldClear(args)) {
+    await removeDatabase(args.logging === "verbose")
+    await removeOutput(args.logging === "verbose")
+  }
+  await fs.mkdir(config.targetFolder, { recursive: true })
 
+  // The wizard runs on a first launch only: no database yet is the one
+  // signal that legitimately means "new project", and --clear does not
+  // change that - a cleared project is still one that was set up.
   if (!args.skip && !dbExists) {
-    const loading = votive({ ...config, verbose: false })
+    // const loading = votive({ ...config, verbose: false })
     await wizard()
-    await (loading)
+    // await (loading)
   }
 
 
-  init(args)
+  // `--editor` is deliberately undocumented: the in-page editor is not
+  // part of 1.0. It reaches the html plugin as config.editor.
+  init({ ...args, editor: Boolean(args.editor) })
 }
 
 

package/cli.js

@@ -0,0 +1,15 @@
+/**
+ * Decisions the CLI makes from its arguments, kept out of bin.js so they
+ * can be tested without launching a server.
+ */
+
+/**
+ * Whether this launch starts cold. `--clear` and `--reset` are the same
+ * flag; anything else is a warm start that reuses the database and the
+ * output, so a second launch on an unchanged site has nothing to do.
+ * The wipe on every launch was a development convenience.
+ * @param {Record<string, unknown>} args - as @bomb.sh/args parses them
+ */
+export function shouldClear(args) {
+  return Boolean(args?.clear || args?.reset)
+}

package/config.js

@@ -1,22 +1,108 @@
+import path from "node:path"
+import { resolveProjectFolder } from "votive"
+import { systemDirectoryFor } from "./systemPaths.js"
+import { secretRouter } from "./secretPaths.js"
 import vowelImagesPlugin from "./plugins/images/index.js"
 import vowelStylesPlugin from "./plugins/styles/index.js"
-import vowelMarkdownPlugin from "./plugins/markdown/index.js"
-import vowelRobotsPlugin from "./plugins/robots/index.js"
-import vowelXMLPlugin from "./plugins/xml/index.js"
+import vowelReadMarkdownPlugin from "./plugins/markdown/index.js"
+import vowelWriteRobotsPlugin from "./plugins/robots/index.js"
+import vowelWriteXMLPlugin from "./plugins/xml/index.js"
 import vowelVectorPlugin from "./plugins/vectors/index.js"
 import vowelFontsPlugin from "./plugins/fonts/index.js"
+import vowelAssetsPlugin from "./plugins/assets/index.js"
+import vowelDeployCloudflarePlugin from "./plugins/deploy-cloudflare/index.js"
+import vowelWriteHTMLPlugin from "./plugins/html/index.js"
+import vowelAtprotoPlugin from "./plugins/atproto/index.js"
+import vowelPublishPlugin from "./plugins/publish/index.js"
+import vowelURLsPlugin from "./plugins/urls/index.js"
 
 /** @import {VotiveConfig} from "votive" */
-export const config = {
-  sourceFolder: ".",
-  destinationFolder: "output",
-  plugins: [
-    vowelMarkdownPlugin,
-    vowelImagesPlugin,
-    vowelStylesPlugin,
-    vowelRobotsPlugin,
-    vowelXMLPlugin,
-    vowelVectorPlugin,
-    vowelFontsPlugin
-  ]
-}
+
+/**
+ * Vowel's routing cascade: secret segments hashed, then the whole path
+ * lowercased. Votive stores a routed path verbatim, and only the
+ * markdown router lowercases its own output - images, fonts, styles and
+ * vectors pass their names through - so this is the one place that
+ * makes every vowel url lowercase. After the hash, not before: the
+ * hash input is the path as the author typed it (secretPaths.js pins
+ * the values), and a hex digest is lowercase already.
+ * @param {string} sourcePath
+ */
+function vowelRouter(sourcePath) {
+  return secretRouter(sourcePath).toLowerCase()
+}
+
+const defaultPlugins = [
+  vowelReadMarkdownPlugin,
+  vowelImagesPlugin,
+  vowelStylesPlugin,
+  vowelWriteRobotsPlugin,
+  vowelWriteXMLPlugin,
+  vowelVectorPlugin,
+  vowelFontsPlugin,
+  vowelAssetsPlugin,
+  vowelDeployCloudflarePlugin,
+  vowelURLsPlugin,
+  vowelAtprotoPlugin,
+  vowelPublishPlugin,
+  vowelWriteHTMLPlugin
+]
+
+/**
+ * Builds a real config for a given project folder - a function, not a
+ * module-level constant, because the folder isn't known until a caller
+ * supplies one. The old shape (a static `export const config` built from
+ * a hardcoded `sourceFolder = "."`) only worked for the CLI, where cwd
+ * genuinely is the project folder; an embedder (vowel-desktop, a future
+ * host) has its own folder that has nothing to do with cwd, and needs
+ * its own targetFolder/databasePath/cacheDirectory to follow it - not a
+ * value baked in at `import vowel from "vowel"` time. See
+ * tasks/desktop-app-architecture.md.
+ *
+ * Vowel targets non-developer end users (via whatever app embeds it),
+ * who could be confused by an `output`/.votive.db/.cache showing up in
+ * their project folder - keep all three in an OS-appropriate system
+ * directory instead, keyed per-project so multiple Vowel sites never
+ * collide.
+ *
+ * `overrides.plugins`, if given, is *added* to vowel's default plugin
+ * list rather than replacing it - an embedder registering its own
+ * native-only commands (a folder picker, "reveal in Finder") shouldn't
+ * have to reimplement markdown/html/images/etc. support just to add one
+ * plugin. Override any of targetFolder/databasePath/cacheDirectory via
+ * `overrides` directly if you want them back in the project directory
+ * (or somewhere else entirely).
+ * @param {string} [sourceFolder] - defaults to the current working
+ *   directory, correct for the CLI. An embedder should always pass an
+ *   explicit, real folder (e.g. from a native folder-picker) - cwd has
+ *   no meaningful relationship to "the user's project" there.
+ * @param {Partial<VotiveConfig> & { plugins?: VotiveConfig["plugins"] }} [overrides]
+ * @returns {VotiveConfig}
+ */
+function createConfig(sourceFolder = ".", overrides = {}) {
+  const resolvedSourceFolder = resolveProjectFolder(sourceFolder)
+  const systemDirectory = systemDirectoryFor(resolvedSourceFolder)
+  const { plugins: extraPlugins, ...rest } = overrides
+
+  return {
+    sourceFolder: resolvedSourceFolder,
+    // Applied before every processor's own router, so a secret folder
+    // hides its images and fonts too - not just its pages. See
+    // secretPaths.js for why this cannot live in a processor.
+    router: vowelRouter,
+    // Fetched link previews live in the project, one YAML file per host,
+    // so they survive a cache wipe, travel with the project, and reach
+    // coworkers through the repo. Visible rather than votive's hidden
+    // default, because the author is meant to find and edit them: the
+    // file is what the site shows. `$` keeps it out of routing, and
+    // votive keeps it out of the source scan.
+    urlStore: path.join(resolvedSourceFolder, "$links"),
+    targetFolder: path.join(systemDirectory, "output"),
+    databasePath: path.join(systemDirectory, ".votive.db"),
+    cacheDirectory: path.join(systemDirectory, ".cache"),
+    plugins: [...defaultPlugins, ...(extraPlugins ?? [])],
+    ...rest
+  }
+}
+
+export { createConfig }

package/extractDate.js

@@ -1,10 +1,36 @@
+const MONTH_INDEXES = {
+  jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5,
+  jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11
+}
+
+/**
+ * Months arrive either as a name ("January", "Sept") or as a number.
+ * @param {string} month
+ */
+function monthIndex(month) {
+  const named = MONTH_INDEXES[String(month).slice(0, 3).toLowerCase()]
+  if (named !== undefined) return named
+  return Number(month) - 1
+}
+
+// Deliberately unanchored: a caller may want the date out of a longer
+// string. Use dateSpan() to tell "this text *is* a date" from "this text
+// mentions one".
+const DATE_PATTERN = /(?:\b(?<first_segment>(?<first_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<first_YYYY>\d\d\d\d)|(?<first_do>(?:\d|[0-3]\d)(?:st|nd|rd|th))|(?<first_dd_or_MM_or_yy>[0-3]\d)|(?<first_d_or_M>\d))(?<first_delimiter>\.| |, |\/|-)?)(?:\b(?<second_segment>(?<second_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<second_YYYY>\d\d\d\d)|(?<second_do>(\d\d)(:?st|nd|rd|th))|(?<second_dd_or_MM_or_yy>[0-3]\d)|(?<second_d_or_M>\d))(?<second_delimiter>\.| |, |\/|-)?)(?:\b(?<third_segment>(?<third_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<third_YYYY>\d\d\d\d)|(?<third_do>(\d\d)(?:st|nd|rd|th))|(?<third_dd_or_MM_or_yy>[0-3]\d)|(?<third_d_or_M>\d)))(?<time>(?<time_delimiter>T|\ | at )(?<H_or_HH>[0-2]?\d):(?<MM>[0-6]\d)(?::(?<SS>00))?(?:\.(?<SSS>\d\d\d))?(?<Z>Z|(?:\+(\d\d):(\d\d)))?(?<meridiam_indicator>am|pm)?)?/i
+
 /**
+ * The part of `text` that looks like a date, or undefined.
  * @param {string} text
  */
-function extractDate(text) {
-  const dateRegex = /(?:\b(?<first_segment>(?<first_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<first_YYYY>\d\d\d\d)|(?<first_do>(?:\d|[0-3]\d)(?:st|nd|rd|th))|(?<first_dd_or_MM_or_yy>[0-3]\d)|(?<first_d_or_M>\d))(?<first_delimiter>\.| |, |\/|-)?)(?:\b(?<second_segment>(?<second_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<second_YYYY>\d\d\d\d)|(?<second_do>(\d\d)(:?st|nd|rd|th))|(?<second_dd_or_MM_or_yy>[0-3]\d)|(?<second_d_or_M>\d))(?<second_delimiter>\.| |, |\/|-)?)(?:\b(?<third_segment>(?<third_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<third_YYYY>\d\d\d\d)|(?<third_do>(\d\d)(?:st|nd|rd|th))|(?<third_dd_or_MM_or_yy>[0-3]\d)|(?<third_d_or_M>\d)))(?<time>(?<time_delimiter>T|\ | at )(?<H_or_HH>[0-2]?\d):(?<MM>[0-6]\d)(?::(?<SS>00))?(?:\.(?<SSS>\d\d\d))?(?<Z>Z|(?:\+(\d\d):(\d\d)))?(?<meridiam_indicator>am|pm)?)?/i
+function dateSpan(text) {
+  return DATE_PATTERN.exec(text)?.[0]
+}
 
-  const dateMatch = dateRegex.exec(text)
+/**
+ * @param {string} text
+ */
+function extractDate(text) {
+  const dateMatch = DATE_PATTERN.exec(text)
   if(!dateMatch) return
 
   const data = {
@@ -73,11 +99,49 @@ function extractDate(text) {
     data.timezone = groups.Z
   }
 
-  const time = groups.time ? `${data.hours}:${data.minutes}:${data.seconds}${data.timezone || ""}` : null
-  const dateString = `${data.year} ${data.month} ${data.day}${time ? " " + time : ""}`
+  // A bare "YYYY M D" string is parsed as local time, which shifts the
+  // date by a day in any timezone east of UTC and by an odd LMT offset
+  // before standardization (Amsterdam in the year 1000 is +00:17:30). The
+  // date an author writes has no timezone, so build it as UTC and only
+  // honour an offset when one was written explicitly.
+  const year = Number(data.year)
+  const month = monthIndex(data.month)
+  const day = parseInt(data.day, 10)
+
+  const hours = data.hours ? Number(data.hours) : 0
+  const minutes = data.minutes ? Number(data.minutes) : 0
+  const seconds = data.seconds ? Number(data.seconds) : 0
+
+  // Date.UTC rolls out-of-range parts over into neighbouring months and
+  // years, so an ISBN's segments would silently become a real date. The
+  // string parse this replaced rejected them, and callers still rely on
+  // that: the frontmatter renderer only treats a value as a date when the
+  // result is valid.
+  const partsAreSane =
+    Number.isInteger(year) &&
+    Number.isInteger(month) && month >= 0 && month <= 11 &&
+    Number.isInteger(day) && day >= 1 && day <= 31
+
+  if (!partsAreSane) return new Date(NaN)
+
+  if (data.timezone) {
+    const pad = (value, width = 2) => String(value).padStart(width, "0")
+    const stamp = `${pad(year, 4)}-${pad(month + 1)}-${pad(day)}` +
+      `T${pad(hours)}:${pad(minutes)}:${pad(seconds)}${data.timezone}`
+    return new Date(stamp)
+  }
+
+  const result = new Date(Date.UTC(year, month, day, hours, minutes, seconds))
+
+  // Catches the rollover that survives the range check - 31 February.
+  const rolled =
+    result.getUTCFullYear() !== year ||
+    result.getUTCMonth() !== month ||
+    result.getUTCDate() !== day
 
-  return new Date(dateString)
+  return rolled ? new Date(NaN) : result
 }
 
 export default extractDate
+export { extractDate, dateSpan }
 

package/index.js

@@ -1,14 +1,23 @@
-import voot from "voot"
-import { config } from "./config.js"
+import { startServer } from "votive"
+import { createConfig } from "./config.js"
 
 /**
  * @param {object} options
  * @property {"verbose" | "essential" | "silent"} logging
+ * @property {string} [sourceFolder] - defaults to the current working
+ *   directory (see createConfig) - a caller with its own project folder
+ *   (vowel-desktop, a future host) should always pass this explicitly.
+ * @returns {Promise<{port: number, server: import("node:http").Server, close: () => Promise<void>}>}
+ *   startServer's own return, passed through. `port` is the bound port, which can
+ *   differ from the one requested; `close()` releases the watchers and the
+ *   listener, which a host serving more than one project over a session
+ *   needs before opening the next one.
  */
-async function init(options) {
-  const cache = await voot({ ...config, ...options })
+async function init(options = {}) {
+  const { sourceFolder, ...overrides } = options
+  const config = createConfig(sourceFolder, overrides)
+  return startServer(config)
 }
 
 
 export default init
-