vowel 0.6.4 → 0.7.0-beta.0

package/plugins/atproto/record.js

@@ -0,0 +1,144 @@
+import { toText } from "hast-util-to-text"
+import { MARKER } from "../../secretPaths.js"
+import createRkey from "./rkey.js"
+
+/**
+ * Which pages become records, and what each record holds. No network:
+ * everything here is a function of the page and its settings, so it runs
+ * in the build, and the publish command only compares and sends.
+ */
+
+const DOCUMENT = "site.standard.document"
+const PUBLICATION = "site.standard.publication"
+
+/** The lexicons vowel can build a record for. */
+const SUPPORTED = [DOCUMENT]
+
+/**
+ * The page's lexicon and, for a secret page, whether it may use it.
+ *
+ * `atproto_lexicon:` cascades from settings.md, and a page's own
+ * frontmatter can set it too. A page under a secret segment (`##`) is published only when
+ * the lexicon was set *inside* its secret scope: in its own frontmatter,
+ * or in a settings.md at or below the secret folder. A lexicon inherited
+ * from above the secret would publish a hidden page to the network by
+ * accident.
+ *
+ * The settings chain is the page-as-folder chain of the routed path
+ * (`blog/post.html` reads `""`, `blog`, `blog/post`), so level `k` holds
+ * the first `k` segments. Routing replaces a segment with its hash but
+ * keeps the depth, so the secret segment at source index `s` is level
+ * `s + 1`, and every level from there down is inside it.
+ * @param {{ source?: string, metadata: Record<string, any> }} target
+ * @param {{ raw: (label: string) => (unknown[] | null)[] | undefined }} settings
+ * @returns {string | undefined}
+ */
+function lexiconFor(target, settings) {
+  const own = target.metadata.fm_atproto_lexicon
+  if (typeof own === "string" && own) return own
+
+  const levels = settings.raw("fm_atproto_lexicon") ?? []
+  const deepest = levels.findLastIndex(values => Array.isArray(values) && values.length > 0)
+  if (deepest === -1) return undefined
+  const lexicon = levels[deepest].at(-1)
+  if (typeof lexicon !== "string" || !lexicon) return undefined
+
+  const segments = (target.source ?? "").split(/[\\/]/)
+  const secret = segments.findIndex(segment => segment.includes(MARKER))
+  if (secret !== -1 && deepest < secret + 1) return undefined
+  return lexicon
+}
+
+/**
+ * The site's origin from `domain:`, the same base the html plugin builds
+ * the canonical link from. No trailing slash, per the lexicon.
+ * @param {unknown} domain
+ */
+function siteOrigin(domain) {
+  if (typeof domain !== "string" || !domain) return undefined
+  const base = domain.startsWith("http") ? domain : `https://${domain}`
+  return new URL(base).origin
+}
+
+/**
+ * The site's publication: one per account and origin, its key derived
+ * from the origin the way a document's is from its URL, so its AT-URI is
+ * known before it exists. A document's `site` names it, and
+ * `/.well-known/site.standard.publication` serves it, which is how the
+ * domain claims it. The record itself is built by the publish command
+ * (publish.js), because its icon is an uploaded image.
+ * @param {string} did
+ * @param {string} origin
+ */
+function publicationURI(did, origin) {
+  return `at://${did}/${PUBLICATION}/${createRkey(origin)}`
+}
+
+/**
+ * A `site.standard.document` record for the page, or the list of what it
+ * is missing. `title`, `publishedAt` and `site` are required by the
+ * lexicon; a page without a date cannot be a document. `site` is the
+ * publication's AT-URI; `origin` is what the page's key is made from.
+ * @param {{ metadata: Record<string, any> }} target
+ * @param {string | undefined} origin
+ * @param {string} [site] - the publication's AT-URI
+ * @returns {{ record: Record<string, unknown> } | { missing: string[] }}
+ */
+function documentRecord(target, origin, site = origin) {
+  const { title, date, prettyURL, description, tags, hastAbstract } = target.metadata
+  const published = date ? new Date(date) : undefined
+  const validDate = published && !Number.isNaN(published.getTime())
+
+  const missing = [
+    ...(origin ? [] : ["domain"]),
+    ...(title ? [] : ["title"]),
+    ...(validDate ? [] : ["date"])
+  ]
+  if (missing.length) return { missing }
+
+  const textContent = hastAbstract ? toText(hastAbstract).trim() : ""
+
+  const record = {
+    $type: DOCUMENT,
+    site,
+    path: prettyURL,
+    title,
+    publishedAt: published.toISOString(),
+    ...(description ? { description } : {}),
+    ...(Array.isArray(tags) && tags.length ? { tags } : {}),
+    ...(textContent ? { textContent } : {})
+  }
+  return { record }
+}
+
+/**
+ * The page's AT-URI and record, or why it has none. `skip` is silent (the
+ * page is not meant to be published). `incomplete` is a page under a
+ * lexicon that lacks a property the lexicon requires; it is not a record,
+ * by design, and is only mentioned under `verbose`. `warning` is a
+ * misconfiguration: a lexicon vowel cannot build.
+ * @param {{ path: string, source?: string, metadata: Record<string, any> }} target
+ * @param {{ did: string, domain: unknown, settings: any }} context
+ * @returns {{ atUri: string, record: Record<string, unknown> } | { skip: true } | { incomplete: string } | { warning: string }}
+ */
+function pageRecord(target, { did, domain, settings }) {
+  const lexicon = lexiconFor(target, settings)
+  if (!lexicon) return { skip: true }
+  if (!SUPPORTED.includes(lexicon)) {
+    return { warning: `lexicon "${lexicon}" is not one vowel can build a record for (supported: ${SUPPORTED.join(", ")})` }
+  }
+
+  const origin = siteOrigin(domain)
+  const site = origin ? publicationURI(did, origin) : undefined
+  const built = documentRecord(target, origin, site)
+  if ("missing" in built) {
+    return { incomplete: `not published to AT Protocol: a ${lexicon} record needs ${built.missing.join(", ")}` }
+  }
+
+  // The key is the page's canonical URL - origin and path - and frozen
+  // (rkey.js), whatever `site` holds.
+  const rkey = createRkey(new URL(String(built.record.path), origin).href)
+  return { atUri: `at://${did}/${lexicon}/${rkey}`, record: built.record }
+}
+
+export { DOCUMENT, PUBLICATION, SUPPORTED, lexiconFor, siteOrigin, publicationURI, documentRecord, pageRecord }

package/plugins/atproto/rkey.js

@@ -0,0 +1,54 @@
+/**
+ * A page's record key, derived from its canonical URL: the site's origin
+ * and the page's published path, e.g. "https://example.com/blog/post".
+ *
+ * Deterministic, so the AT-URI is known on the first build, before any
+ * record exists, and the same page gets the same key on every machine. No
+ * ledger: the URL is the identity. The domain is part of it, so two sites
+ * publishing to one account never share a key, and a site that changes
+ * domain gets new keys: the documents now live somewhere else. The old
+ * records are *not* deleted by the next publish, because their `site` is
+ * the old domain and publish only deletes records whose `site` is this
+ * site's. A move that changes one page's URL, on the same domain, does
+ * delete that page's old record.
+ *
+ * `site.standard.document` declares `key: tid`, so the key must be shaped
+ * like a TID: 13 characters of base32-sortable, with the top bit clear.
+ * It is 63 bits of FNV-1a over the URL's UTF-8 bytes, which clears the
+ * top bit by construction. A real TID encodes a timestamp and this one
+ * does not, so keys do not sort by date. Nothing in site.standard relies
+ * on that.
+ *
+ * **The function is frozen once anything is published.** Changing the
+ * hash, its input or its encoding moves every page to a new key. The
+ * next publish would then delete and recreate every record.
+ */
+
+const ALPHABET = "234567abcdefghijklmnopqrstuvwxyz"
+const OFFSET = 0xcbf29ce484222325n
+const PRIME = 0x100000001b3n
+const MASK_64 = (1n << 64n) - 1n
+const MASK_63 = (1n << 63n) - 1n
+const LENGTH = 13
+
+/** @param {string} text */
+function fnv1a63(text) {
+  const bytes = Buffer.from(text, "utf8")
+  const hash = bytes.reduce((h, byte) => ((h ^ BigInt(byte)) * PRIME) & MASK_64, OFFSET)
+  return hash & MASK_63
+}
+
+/**
+ * @param {string} canonicalURL - e.g. "https://example.com/blog/post"
+ * @returns {string} a TID-shaped record key
+ */
+function createRkey(canonicalURL) {
+  const hash = fnv1a63(canonicalURL)
+  const characters = Array.from({ length: LENGTH }, (_, index) => {
+    const shift = BigInt(5 * (LENGTH - 1 - index))
+    return ALPHABET[Number((hash >> shift) & 31n)]
+  })
+  return characters.join("")
+}
+
+export default createRkey

package/plugins/deploy-cloudflare/index.js

@@ -1,5 +1,6 @@
 import votive from "votive"
 import { spawn } from "node:child_process"
+import path from "node:path"
 
 /**
  * Publishes a full build to Cloudflare Pages via `wrangler pages deploy`.
@@ -8,7 +9,7 @@ import { spawn } from "node:child_process"
  * happens to already be running against this config - a command's
  * context (config, notify) has no reference to a live server's own build
  * queue, and this needs to behave identically whether triggered from the
- * CLI (no server at all, see voot's runCommand) or a live "Publish"
+ * CLI (no server at all, see votive's runCommand) or a live "Publish"
  * button over WS. Modest redundant cost when a dev server IS already
  * running (bundle() is cheap when nothing's stale), traded for one
  * deploy command that works the same everywhere.
@@ -25,25 +26,37 @@ import { spawn } from "node:child_process"
  * @param {{ config: import("votive").VotiveConfig & { cloudflareProjectName?: string }, notify: (message: object) => void }} context
  */
 async function deployToCloudflarePages(payload, { config, notify }) {
-  if (!config.cloudflareProjectName) throw new Error("config.cloudflareProjectName is required to deploy")
-
   notify({ status: "progress", message: "Building..." })
 
-  const queue = await votive({ ...config, verbose: false })
-  const { runBuffers, runFetches } = await queue()
-
   // Unlike a dev server's own rebuilds, a deploy needs everything done -
-  // there's no "next edit" to stay responsive for, so these are awaited
-  // fully instead of fired via runDeferred().
-  if (runBuffers) await runBuffers()
-  if (runFetches) await runFetches()
+  // there's no "next edit" to stay responsive for - so the deferred
+  // work (image derivatives, link previews) is awaited, and the site is
+  // closed: the database is a cache on disk, and this process is done
+  // with it.
+  const site = await votive({ ...config, verbose: false })
+  await (await site.build()).deferred
+  const setting = site.database.setting.getByFolder("").lastNonNull("fm_cloudflare_project")
+  await site.close()
+
+  // The Pages project, from the command's payload (`vowel --command
+  // deploy --payload '{"projectName":"my-site"}'`, or a Publish button's
+  // body), the root settings.md's `cloudflare_project:`, or the config an
+  // embedder built.
+  const projectName = payload?.projectName ?? setting ?? config.cloudflareProjectName
+  if (!projectName) throw new Error("a Cloudflare Pages project name is required to deploy: set cloudflare_project in the root settings.md, or pass {\"projectName\": \"…\"} as the payload")
+
+  // `{"dryRun": true}` builds and stops short of wrangler.
+  if (payload?.dryRun) {
+    notify({ status: "done", message: `Would deploy ${config.targetFolder} to Cloudflare Pages project ${projectName}` })
+    return { deployed: false, projectName, dryRun: true }
+  }
 
   notify({ status: "progress", message: `Publishing ${config.targetFolder} to Cloudflare Pages...` })
 
   return new Promise((resolve, reject) => {
     const proc = spawn(
       "wrangler",
-      ["pages", "deploy", config.targetFolder, "--project-name", config.cloudflareProjectName],
+      ["pages", "deploy", config.targetFolder, "--project-name", projectName],
       { stdio: ["ignore", "pipe", "pipe"] }
     )
 
@@ -55,17 +68,17 @@ async function deployToCloudflarePages(payload, { config, notify }) {
 
     proc.on("error", reject) // e.g. wrangler isn't installed
     proc.on("exit", code => {
-      if (code === 0) resolve({ deployed: true })
+      if (code === 0) resolve({ deployed: true, projectName })
       else reject(new Error(`wrangler exited with code ${code}`))
     })
   })
 }
 
 /**
- * Not part of vowel's default plugin list (see config.js) - deploying to
- * Cloudflare Pages specifically is an opt-in choice a site adds for
- * itself, along with its own `cloudflareProjectName`, not something
- * every vowel site should get by default.
+ * In vowel's default plugin list (config.js), so `vowel --command
+ * deploy` reaches it from any project. Registering a command costs
+ * nothing until it is invoked, and invoking it needs a project name,
+ * so a site that deploys elsewhere never meets it.
  * @type {import("votive").VotivePlugin}
  */
 const vowelDeployCloudflarePlugin = {
@@ -76,3 +89,4 @@ const vowelDeployCloudflarePlugin = {
 }
 
 export default vowelDeployCloudflarePlugin
+export { deployToCloudflarePages }

package/plugins/fonts/index.js

@@ -1,38 +1,35 @@
-import { readFile } from "node:fs/promises"
 /** @import * as Votive from "votive" */
 
-/** @type {Votive.ProcessorWrite} */
-async function writeFile(target, settings, api, config) {
-  const buffer = await readFile(target.abstract.filePath)
-  return {
-    data: buffer,
-  }
-}
-
-function readFont(filePath) {
-  return {
-    abstract: { filePath },
-    metadata: {}
-  }
+/**
+ * A font the project ships is copied straight through: target.buffer()
+ * resolves the source against sourceFolder at the moment of reading, so
+ * nothing about this machine is ever stored. The @font-face that uses
+ * it is the author's, in their own stylesheet.
+ *
+ * Vowel bundles no fonts of its own any more - the families and their
+ * stubs went with the typography ramps into TypographyStyles.css, which
+ * names a brand family through --font-*-brand and falls back to the
+ * system stack. Fonts by url: tasks/2-in-progress/load-fonts.md.
+ * @type {Votive.ProcessorWrite}
+ */
+function writeFile(target) {
+  return { data: target.buffer() }
 }
 
 /** @type {Votive.VotiveProcessor} */
 const fontsReader = {
   format: "buffer",
   extensions: [".woff", ".woff2", ".ttf", ".otf"],
-  readFile: readFont,
+  router: ({ name, dir, ext }) => ({ name, dir, ext }),
+  // A font carries no metadata worth inferring.
+  readFile: () => ({ metadata: {} }),
   writeFile
 }
 
 /** @type {Votive.VotivePlugin} */
 const vowelFontsPlugin = {
   name: "vowel-fonts",
-  processors: [fontsReader],
-  router: ({ name, dir, ext }) => {
-    return {
-      name, dir, ext
-    }
-  }
+  processors: [fontsReader]
 }
 
 export default vowelFontsPlugin

package/plugins/html/assets/bundle-BeK1Hptv.css

@@ -0,0 +1,21 @@
+@layer svedit-defaults {
+	:root {
+		/* Primary accent for active editing controls, carets, and selections. */
+		--editing: oklch(60% 0.22 283);
+		/* Low-opacity version of the editing accent for passive highlights. */
+		--editing-muted: oklch(from var(--editing) l c h / 0.1);
+		/* Low-emphasis strokes and outlines, such as inactive node gaps. */
+		--editing-stroke: color-mix(in oklch, currentColor 25%, transparent);
+		/* Foreground color for content displayed on the editing accent. */
+		--editing-foreground: oklch(100% 0 0);
+	}
+}
+
+@layer svedit-defaults {
+	@keyframes node-caret-blink {
+		0%, 60% { opacity: 1; }
+		68% { opacity: 0; }
+		88% { opacity: 0; }
+		100% { opacity: 1; }
+	}
+}

package/plugins/html/bundle/assets/index-BeK1Hptv.css

@@ -0,0 +1,21 @@
+@layer svedit-defaults {
+	:root {
+		/* Primary accent for active editing controls, carets, and selections. */
+		--editing: oklch(60% 0.22 283);
+		/* Low-opacity version of the editing accent for passive highlights. */
+		--editing-muted: oklch(from var(--editing) l c h / 0.1);
+		/* Low-emphasis strokes and outlines, such as inactive node gaps. */
+		--editing-stroke: color-mix(in oklch, currentColor 25%, transparent);
+		/* Foreground color for content displayed on the editing accent. */
+		--editing-foreground: oklch(100% 0 0);
+	}
+}
+
+@layer svedit-defaults {
+	@keyframes node-caret-blink {
+		0%, 60% { opacity: 1; }
+		68% { opacity: 0; }
+		88% { opacity: 0; }
+		100% { opacity: 1; }
+	}
+}