@pathmx/core 0.5.0

package/document.ts

@@ -0,0 +1,194 @@
+import type { DocumentAsset, Source } from "./plugins/types"
+import type { SourceBlock } from "./source"
+import { escapeHtml } from "./util"
+
+/**
+ * Canonical head order: charset, title, other metas, preloads, stylesheets,
+ * inline styles, scripts. Contribution order breaks ties (Array.sort is
+ * stable), so plugins never need a placement option — the engine owns layout.
+ */
+export function documentAssetRank(asset: DocumentAsset) {
+  if (asset.type === "meta") return asset.attrs.charset != null ? 0 : 2
+  if (asset.type === "title") return 1
+  if (asset.type === "preload") return 3
+  if (asset.type === "stylesheet") return 4
+  if (asset.type === "style") return 5
+  return 6
+}
+
+export function documentAssetKey(asset: DocumentAsset) {
+  if (asset.type === "style") return `style:${asset.text}`
+  if (asset.type === "script") {
+    if ("name" in asset && asset.name) return `script:name:${asset.name}`
+    if ("source" in asset) return `script:source:${asset.source}`
+    return "href" in asset ? `script:${asset.href}` : `script:${asset.text}`
+  }
+  if (asset.type === "title") return "title"
+  if (asset.type === "preload") {
+    return `preload:${asset.href}:${asset.as}`
+  }
+  if (asset.type === "meta") {
+    const { charset, name, property } = asset.attrs
+    return `meta:${charset != null ? "charset" : (name ?? property ?? JSON.stringify(asset.attrs))}:${asset.attrs.media ?? ""}`
+  }
+  if ("name" in asset && asset.name) return `stylesheet:name:${asset.name}`
+  return `stylesheet:${"href" in asset ? asset.href : ""}`
+}
+
+function pushUniqueAsset(assets: DocumentAsset[], asset: DocumentAsset) {
+  const key = documentAssetKey(asset)
+  if (assets.some((item) => documentAssetKey(item) === key)) return
+  assets.push(
+    Object.freeze(
+      asset.type === "meta"
+        ? { ...asset, attrs: Object.freeze({ ...asset.attrs }) }
+        : { ...asset },
+    ),
+  )
+}
+
+/** Page and document contexts share one uniqueness-preserving asset bag. */
+export function createAssetBag(assets: DocumentAsset[] = []) {
+  return {
+    assets,
+    addAsset(...items: DocumentAsset[]) {
+      for (const asset of items) pushUniqueAsset(assets, asset)
+    },
+  }
+}
+
+export function closeInline(text: string, tag: "style" | "script") {
+  return text.replace(new RegExp(`<\\/${tag}`, "gi"), `<\\/${tag}`)
+}
+
+export function renderDocumentAssets(assets: readonly DocumentAsset[]) {
+  return assets
+    .map((asset) => {
+      if (asset.type === "title") {
+        return `<title>${escapeHtml(asset.text)}</title>`
+      }
+      if (asset.type === "meta") {
+        const attrs = Object.entries(asset.attrs)
+          .map(([key, value]) => ` ${key}="${escapeHtml(value)}"`)
+          .join("")
+        return `<meta${attrs}>`
+      }
+      if (asset.type === "preload") {
+        const contentType = asset.contentType
+          ? ` type="${escapeHtml(asset.contentType)}"`
+          : ""
+        const crossorigin = asset.crossorigin ? " crossorigin" : ""
+        return `<link rel="preload" href="${escapeHtml(asset.href)}" as="${escapeHtml(asset.as)}"${contentType}${crossorigin}>`
+      }
+      if (asset.type === "stylesheet") {
+        const href = "href" in asset ? asset.href : ""
+        const media = asset.media ? ` media="${escapeHtml(asset.media)}"` : ""
+        return `<link rel="stylesheet" href="${escapeHtml(href)}"${media}>`
+      }
+      if (asset.type === "style") {
+        return `<style>${closeInline(asset.text, "style")}</style>`
+      }
+      const moduleAttr = asset.module ? ` type="module"` : ""
+      if ("href" in asset) {
+        return `<script${moduleAttr} src="${escapeHtml(asset.href)}"></script>`
+      }
+      if ("source" in asset) {
+        throw new Error(`Unresolved authored script asset: ${asset.source}`)
+      }
+      return `<script${moduleAttr}>${closeInline(asset.text, "script")}</script>`
+    })
+    .join("")
+}
+
+export function headingIdsForBlock(source: Source, block: SourceBlock) {
+  let offset = 0
+  for (const item of source.blocks) {
+    if (item.id === block.id) {
+      return source.headings.slice(offset, offset + item.headings.length)
+    }
+    offset += item.headings.length
+  }
+  return block.headings
+}
+
+type HeadingRef = { depth: number; id: string }
+
+const TASK_INSTRUCTION =
+  /(<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox"[^>]*><strong>[\s\S]*?<\/strong>)\r?\n/g
+
+/** Preserve exam-style instruction lines beneath a leading bold task title. */
+export function preserveTaskInstructions(html: string) {
+  if (!html.includes('class="task-list-item"')) return html
+  return html.replace(TASK_INSTRUCTION, "$1<br>")
+}
+
+/** Normalize Markdown heading ids and add accessible sibling permalinks. */
+export function applyHeadingPermalinks(
+  html: string,
+  headings: readonly HeadingRef[],
+  renderedHeadings: readonly HeadingRef[],
+) {
+  if (!headings.length) return html
+  let index = 0
+  return html.replace(
+    /<h([1-6]) id="([^"]*)">[\s\S]*?<\/h\1>/g,
+    (headingHtml, renderedDepth: string, renderedId: string) => {
+      const heading = headings[index]
+      const renderedHeading = renderedHeadings[index]
+      if (
+        !heading ||
+        !renderedHeading ||
+        Number(renderedDepth) !== renderedHeading.depth ||
+        renderedId !== escapeHtml(renderedHeading.id)
+      )
+        return headingHtml
+
+      index++
+      const id = escapeHtml(heading.id)
+      const normalizedHtml = headingHtml.replace(
+        `<h${renderedDepth} id="${renderedId}">`,
+        `<h${renderedDepth} id="${id}">`,
+      )
+      if (!id) return normalizedHtml
+      return [
+        `<div class="pmx-heading level-h${renderedDepth}">`,
+        normalizedHtml,
+        `<a class="pmx-heading-anchor" href="#${id}" aria-labelledby="${id}">`,
+        `</a></div>`,
+      ].join("")
+    },
+  )
+}
+
+const BLOCK_FLOW_OPEN = '<template data-pathmx-block-flow="">'
+const BLOCK_FLOW_CLOSE = "</template>"
+
+/** Mark compiled Block sections that replace their authored placeholder Block. */
+export function wrapBlockFlow(html: string) {
+  return `${BLOCK_FLOW_OPEN}${html}${BLOCK_FLOW_CLOSE}`
+}
+
+/** Return a complete Block-flow expansion, leaving ordinary Block HTML alone. */
+export function unwrapBlockFlow(html: string) {
+  const value = html.trim()
+  if (!value.startsWith(BLOCK_FLOW_OPEN) || !value.endsWith(BLOCK_FLOW_CLOSE)) {
+    return
+  }
+  return value.slice(BLOCK_FLOW_OPEN.length, -BLOCK_FLOW_CLOSE.length).trim()
+}
+
+export function wrapBlockSection(
+  block: Pick<SourceBlock, "id" | "path" | "type">,
+  html: string,
+  options?: { id?: string },
+) {
+  const id = options?.id ?? block.id
+  const typeAttr =
+    block.type !== "block" ? ` data-type="${escapeHtml(block.type)}"` : ""
+  return `<section id="${escapeHtml(id)}" data-pmx-block data-pmx-block-path="${escapeHtml(block.path)}" class="pmx-prose"${typeAttr}>\n${html.trim()}\n</section>`
+}
+
+/** The canonical authored page region inserted into zero or more layouts. */
+export function wrapPageArticle(source: Source, html: string) {
+  return `<article class="pmx-document" data-type="${escapeHtml(source.type)}" data-source="${escapeHtml(source.id)}">${html}</article>`
+}

package/environment.ts

@@ -0,0 +1,110 @@
+import type { SqlConnection } from "./database.ts"
+
+type Awaitable<T> = T | Promise<T>
+
+export type HtmlElement = {
+  readonly tagName: string
+  readonly attributes: Iterable<[string, string]>
+  getAttribute(name: string): string | null
+  setAttribute(name: string, value: string): void
+  removeAttribute(name: string): void
+  before(content: string, options?: { html?: boolean }): void
+  after(content: string, options?: { html?: boolean }): void
+  prepend(content: string, options?: { html?: boolean }): void
+  setInnerContent(content: string, options?: { html?: boolean }): void
+  remove(): void
+  onEndTag(handler: () => void): void
+}
+
+export type HtmlTextChunk = {
+  readonly text: string
+  readonly lastInTextNode: boolean
+  remove(): void
+  after(content: string, options?: { html?: boolean }): void
+}
+
+export type HtmlRewriteHandler = {
+  element?(element: HtmlElement): void
+  text?(chunk: HtmlTextChunk): void
+}
+
+export type HtmlRewriteRule = readonly [
+  selector: string,
+  handler: HtmlRewriteHandler,
+]
+
+export type HtmlStringRewrite = (
+  html: string,
+  rules: readonly HtmlRewriteRule[],
+) => string
+
+export type HtmlRewrite = {
+  (html: string, rules: readonly HtmlRewriteRule[]): string
+  (response: Response, rules: readonly HtmlRewriteRule[]): Response
+}
+
+export type PathMXStorage = {
+  /** Return file keys relative to `root`. */
+  list: (root: string) => Awaitable<Iterable<string>>
+  readText: (path: string) => Awaitable<string>
+  readBlob: (path: string) => Awaitable<Blob>
+  /** Write text, creating any parent containers required by the adapter. */
+  writeText: (path: string, content: string) => Awaitable<void>
+  delete: (path: string) => Awaitable<void>
+  /** Return whether a readable storage object exists at `path`. */
+  exists: (path: string) => Awaitable<boolean>
+}
+
+export type PathMXYaml = {
+  parse: (text: string) => unknown
+  stringify: (value: Record<string, unknown>) => string
+}
+
+export type PathMXPath = {
+  basename: (path: string) => string
+  dirname: (path: string) => string
+  extname: (path: string) => string
+  join: (...paths: string[]) => string
+  normalize: (path: string) => string
+  relative: (from: string, to: string) => string
+  resolve: (...paths: string[]) => string
+}
+
+export type PathMXDatabaseEnvironment = Readonly<{
+  /** Join an adapter-owned state root to a database filename. */
+  path(root: string, filename: string): string
+  open(path: string): Awaitable<SqlConnection>
+}>
+
+/** One output of bundling a browser entrypoint, held in memory. */
+export type BundledAsset =
+  | {
+      /** Output-relative artifact path, e.g. `client.js`. */
+      path: string
+      type: "script" | "style"
+      text: string
+    }
+  | {
+      /** Binary output retained without a lossy text conversion. */
+      path: string
+      type: "file"
+      blob: Blob
+    }
+
+export type PathMXEnvironment = {
+  renderMarkdown: (markdown: string) => string
+  /** Apply selector transforms through the runtime's HTML implementation. */
+  rewriteHtml: HtmlRewrite
+  /** Load a package-owned asset independently of repository storage. */
+  loadAsset: (url: URL) => Awaitable<Blob>
+  /** Bundle a browser entrypoint (ts/tsx/js/css) into in-memory assets. */
+  bundle: (entrypoint: string | URL) => Promise<BundledAsset[]>
+  /** Resolve a server module; adapters may use imports, manifests, or maps. */
+  loadModule: (specifier: string) => Promise<unknown | undefined>
+  /** POSIX logical path operations; these are not storage/filesystem calls. */
+  path: PathMXPath
+  yaml: PathMXYaml
+  storage: PathMXStorage
+  /** Optional SQL capability, opened lazily only by plugins that declare state. */
+  database?: PathMXDatabaseEnvironment
+}

package/environments/bun-plugins.ts

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs"
+import { readdir } from "node:fs/promises"
+import { join, resolve } from "node:path"
+import type { Log } from "../log.ts"
+import {
+  expandPluginContributions,
+  type PluginContribution,
+} from "../plugins/preset.ts"
+import { projectDirectory } from "../project.ts"
+import { bunEnvironment } from "./bun.ts"
+
+const TOP_LEVEL_PLUGIN = /^[^/]+\.plugin\.(?:ts|tsx|js|jsx)$/
+const DIRECTORY_PLUGIN = /^index\.plugin\.(?:ts|tsx|js|jsx)$/
+
+export function defaultPluginsRoot(pathsRoot: string) {
+  return projectDirectory(pathsRoot, "plugins")
+}
+
+async function pluginEntrypoints(root: string) {
+  if (!existsSync(root)) return []
+  const entries = await readdir(root, { withFileTypes: true })
+  const topLevel = entries
+    .filter((entry) => entry.isFile() && TOP_LEVEL_PLUGIN.test(entry.name))
+    .map((entry) => join(root, entry.name))
+  const nested = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map(async (directory) => {
+        const directoryRoot = join(root, directory.name)
+        const children = await readdir(directoryRoot, { withFileTypes: true })
+        return children
+          .filter(
+            (child) => child.isFile() && DIRECTORY_PLUGIN.test(child.name),
+          )
+          .map((child) => join(directoryRoot, child.name))
+      }),
+  )
+  return [...topLevel, ...nested.flat()].sort()
+}
+
+function repositoryContribution(
+  value: unknown,
+  entrypoint: string,
+): PluginContribution {
+  try {
+    expandPluginContributions([value])
+    return value as PluginContribution
+  } catch (cause) {
+    throw new Error(
+      `Repository Plugin ${entrypoint} must default-export a Plugin, PluginFactory, or PluginPreset.`,
+      { cause },
+    )
+  }
+}
+
+/** Load deterministic, trusted server plugins authored beside a Bun repository. */
+export async function discoverRepositoryPlugins(pathsRoot: string, log: Log) {
+  const plugins: PluginContribution[] = []
+  const root = resolve(defaultPluginsRoot(pathsRoot))
+  for (const entrypoint of await pluginEntrypoints(root)) {
+    const module = (await bunEnvironment.loadModule(entrypoint)) as
+      { default?: unknown } | undefined
+    const contribution = repositoryContribution(module?.default, entrypoint)
+    log.info("plugin.discover", { entrypoint })
+    plugins.push(contribution)
+  }
+  return plugins
+}

package/environments/bun-publish.ts

@@ -0,0 +1,194 @@
+import { copyFile, mkdir, mkdtemp, rename, rm } from "node:fs/promises"
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  parse,
+  relative,
+  resolve,
+  sep,
+} from "node:path"
+import type {
+  PublicationBundle,
+  PublicationManifest,
+  PublicationStore,
+} from "../publish/model.ts"
+
+const WRITE_CONCURRENCY = 32
+
+async function writeBatches<T>(
+  items: readonly T[],
+  write: (item: T) => Promise<void>,
+) {
+  for (let start = 0; start < items.length; start += WRITE_CONCURRENCY) {
+    await Promise.all(items.slice(start, start + WRITE_CONCURRENCY).map(write))
+  }
+}
+
+function isMissing(error: unknown) {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  )
+}
+
+async function moveExisting(path: string, backup: string) {
+  try {
+    await rename(path, backup)
+    return true
+  } catch (error) {
+    if (isMissing(error)) return false
+    throw error
+  }
+}
+
+function artifactPath(root: string, artifact: string) {
+  const path = resolve(root, artifact)
+  const local = relative(root, path)
+  if (
+    !artifact ||
+    isAbsolute(artifact) ||
+    local === ".." ||
+    local.startsWith(`..${sep}`) ||
+    isAbsolute(local)
+  ) {
+    throw new Error(`Invalid publication artifact path: ${artifact}`)
+  }
+  if (local === join(".pathmx", "manifest.json")) {
+    throw new Error(
+      "Publication artifact conflicts with .pathmx/manifest.json.",
+    )
+  }
+  return path
+}
+
+function directoryStore(root: string): PublicationStore {
+  return Object.freeze({
+    async put(artifact: string, body: Blob) {
+      const path = artifactPath(root, artifact)
+      await mkdir(dirname(path), { recursive: true })
+      await Bun.write(path, body)
+      return Object.freeze({
+        size: body.size,
+        read: async () => Bun.file(path),
+      })
+    },
+  })
+}
+
+async function writeArtifacts(
+  store: PublicationStore,
+  bundle: PublicationBundle,
+) {
+  await writeBatches(bundle.artifacts, async (item) => {
+    await store.put(item.path, await item.read())
+  })
+}
+
+function pageOutput(pathname: string) {
+  return pathname === "/"
+    ? "index.html"
+    : join(pathname.replace(/^\/+|\/+$/g, ""), "index.html")
+}
+
+async function writePageRoutes(root: string, bundle: PublicationBundle) {
+  const artifacts = new Map(
+    bundle.artifacts.map((artifact) => [artifact.path, artifact]),
+  )
+  const pages = bundle.manifest.routes.filter((route) => route.type === "page")
+  await writeBatches(pages, async (route) => {
+    const representation = route.representations.find(
+      (representation) =>
+        representation.default && representation.type === "html",
+    )
+    const artifact = representation
+      ? artifacts.get(representation.artifact)
+      : undefined
+    if (!artifact) {
+      throw new Error(
+        `Page route has no default HTML artifact: ${route.pathname}`,
+      )
+    }
+    const output = pageOutput(route.pathname)
+    const collision = artifacts.get(output)
+    if (collision && collision !== artifact) {
+      throw new Error(
+        `Directory publication cannot represent both ${route.pathname} and /${output}.`,
+      )
+    }
+    const path = artifactPath(root, output)
+    await mkdir(dirname(path), { recursive: true })
+    await copyFile(artifactPath(root, artifact.path), path)
+  })
+}
+
+async function finalizePublication(root: string, bundle: PublicationBundle) {
+  await writePageRoutes(root, bundle)
+  const manifestPath = join(root, ".pathmx", "manifest.json")
+  await mkdir(dirname(manifestPath), { recursive: true })
+  await Bun.write(manifestPath, JSON.stringify(bundle.manifest, null, 2) + "\n")
+}
+
+async function publishAtomically<T>(
+  output: string,
+  prepare: (staging: string) => Promise<T>,
+) {
+  const destination = resolve(output)
+  if (destination === parse(destination).root) {
+    throw new Error("Publication output cannot be a filesystem root.")
+  }
+  const parent = dirname(destination)
+  await mkdir(parent, { recursive: true })
+  const staging = await mkdtemp(join(parent, `.${basename(destination)}-`))
+  const backup = `${staging}.previous`
+  let movedExisting = false
+  try {
+    const result = await prepare(staging)
+    movedExisting = await moveExisting(destination, backup)
+    try {
+      await rename(staging, destination)
+    } catch (error) {
+      if (movedExisting) {
+        await rename(backup, destination)
+        movedExisting = false
+      }
+      throw error
+    }
+    if (movedExisting) {
+      await rm(backup, { recursive: true, force: true }).catch(() => undefined)
+      movedExisting = false
+    }
+    return result
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true })
+    if (movedExisting) await rename(backup, destination)
+    throw error
+  }
+}
+
+/** Materialize a prebuilt publication bundle as a directory-style static tree. */
+export async function writePublication(
+  bundle: PublicationBundle,
+  output: string,
+) {
+  return publishAtomically(output, async (staging) => {
+    await writeArtifacts(directoryStore(staging), bundle)
+    await finalizePublication(staging, bundle)
+    return bundle.manifest
+  })
+}
+
+/** Build into private directory staging and atomically expose the completed tree. */
+export async function publishToDirectory(
+  output: string,
+  build: (store: PublicationStore) => Promise<PublicationBundle>,
+): Promise<PublicationManifest> {
+  return publishAtomically(output, async (staging) => {
+    const bundle = await build(directoryStore(staging))
+    await finalizePublication(staging, bundle)
+    return bundle.manifest
+  })
+}