@pathmx/core 0.5.0

package/pattern.ts

@@ -0,0 +1,314 @@
+import type { PathMXEnvironment } from "./environment.ts"
+import type { StandardSchemaV1 } from "./schema/standard.ts"
+import { formatSchemaIssues } from "./schema/standard.ts"
+import {
+  readTextFileState,
+  sameTextFileState,
+  type TextFileState,
+} from "./text-file.ts"
+
+type Awaitable<T> = T | Promise<T>
+
+export type PatternRoot = "paths" | "project"
+
+export type PatternFile = Readonly<{
+  root: PatternRoot
+  path: string
+  content: string
+}>
+
+export type Pattern<Input = undefined> = Readonly<{
+  id: string
+  description?: string
+  input?: StandardSchemaV1<unknown, Input>
+  generate(input: Input): Awaitable<readonly PatternFile[]>
+}>
+
+export type PatternConflictPolicy = "error" | "preserve" | "overwrite"
+
+export type PatternInstallOptions = Readonly<{
+  conflicts?: PatternConflictPolicy
+}>
+
+export type PatternFileStatus = "create" | "unchanged" | "conflict" | "replace"
+
+export type PatternPlanFile = PatternFile &
+  Readonly<{
+    destination: string
+    status: PatternFileStatus
+    before: TextFileState
+  }>
+
+export type PatternPlan = Readonly<{
+  pattern: string
+  conflicts: PatternConflictPolicy
+  files: readonly PatternPlanFile[]
+}>
+
+export type PatternRoots = Readonly<{
+  paths: string
+  project: string
+}>
+
+export type PatternInstaller = Readonly<{
+  plan<Input>(
+    pattern: Pattern<Input>,
+    input?: unknown,
+    options?: PatternInstallOptions,
+  ): Promise<PatternPlan>
+  apply(plan: PatternPlan): Promise<PatternPlan>
+  install<Input>(
+    pattern: Pattern<Input>,
+    input?: unknown,
+    options?: PatternInstallOptions,
+  ): Promise<PatternPlan>
+}>
+
+export class PatternError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PatternError"
+  }
+}
+
+const PATTERN_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*(?::[a-z0-9]+(?:-[a-z0-9]+)*)?$/
+
+function canonicalPatternId(id: string) {
+  if (!PATTERN_ID.test(id)) throw new PatternError(`Invalid Pattern id: ${id}`)
+  return id
+}
+
+/** Preserve input inference for install-time project Patterns. */
+export function definePattern<Input = undefined>(pattern: Pattern<Input>) {
+  return pattern
+}
+
+async function validateInput<Input>(pattern: Pattern<Input>, input: unknown) {
+  if (!pattern.input) {
+    if (input !== undefined) {
+      throw new PatternError(`Pattern ${pattern.id} does not accept input.`)
+    }
+    return undefined as Input
+  }
+  const result = await pattern.input["~standard"].validate(input)
+  if (result.issues) {
+    throw new PatternError(
+      `Invalid input for Pattern ${pattern.id}: ${formatSchemaIssues(result.issues)}`,
+    )
+  }
+  return result.value
+}
+
+function normalizedFile(
+  environment: Pick<PathMXEnvironment, "path">,
+  roots: PatternRoots,
+  file: PatternFile,
+) {
+  if (file.root !== "paths" && file.root !== "project") {
+    throw new PatternError(`Invalid Pattern root: ${String(file.root)}`)
+  }
+  if (typeof file.content !== "string") {
+    throw new PatternError(`Pattern file content must be text: ${file.path}`)
+  }
+  const raw = file.path.replaceAll("\\", "/")
+  if (
+    !raw ||
+    raw.startsWith("/") ||
+    /^[a-zA-Z]:\//.test(raw) ||
+    raw.split("/").includes("..")
+  ) {
+    throw new PatternError(
+      `Pattern path escapes its ${file.root} root: ${file.path}`,
+    )
+  }
+  const path = environment.path.normalize(raw)
+  if (!path || path === ".") {
+    throw new PatternError(`Invalid Pattern path: ${file.path}`)
+  }
+  const root = roots[file.root]
+  const destination = environment.path.join(root, path)
+  const relative = environment.path.relative(root, destination)
+  if (!relative || relative === ".." || relative.startsWith("../")) {
+    throw new PatternError(
+      `Pattern path escapes its ${file.root} root: ${file.path}`,
+    )
+  }
+  return Object.freeze({ ...file, path, destination })
+}
+
+function status(
+  before: TextFileState,
+  content: string,
+  conflicts: PatternConflictPolicy,
+): PatternFileStatus {
+  if (before.type === "missing") return "create"
+  if (before.content === content) return "unchanged"
+  return conflicts === "overwrite" ? "replace" : "conflict"
+}
+
+function conflictPolicy(conflicts: PatternConflictPolicy = "error") {
+  if (
+    conflicts !== "error" &&
+    conflicts !== "preserve" &&
+    conflicts !== "overwrite"
+  ) {
+    throw new PatternError(
+      `Invalid Pattern conflict policy: ${String(conflicts)}`,
+    )
+  }
+  return conflicts
+}
+
+async function rollback(
+  storage: PathMXEnvironment["storage"],
+  attempted: readonly PatternPlanFile[],
+) {
+  const errors: unknown[] = []
+  for (const file of [...attempted].reverse()) {
+    try {
+      const current = await readTextFileState(storage, file.destination)
+      if (sameTextFileState(current, file.before)) continue
+      if (current.type !== "present" || current.content !== file.content) {
+        throw new PatternError(
+          `Pattern destination changed during rollback: ${file.destination}`,
+        )
+      }
+      if (file.before.type === "missing") {
+        await storage.delete(file.destination)
+      } else {
+        await storage.writeText(file.destination, file.before.content)
+      }
+    } catch (error) {
+      errors.push(error)
+    }
+  }
+  return errors
+}
+
+export function createPatternInstaller(
+  environment: Pick<PathMXEnvironment, "path" | "storage">,
+  roots: PatternRoots,
+): PatternInstaller {
+  const installRoots = Object.freeze({ ...roots })
+  const resolve = (file: PatternFile) =>
+    normalizedFile(environment, installRoots, file)
+
+  const plan: PatternInstaller["plan"] = async (pattern, input, options) => {
+    const id = canonicalPatternId(pattern.id)
+    const conflicts = conflictPolicy(options?.conflicts)
+    const generated = await pattern.generate(
+      await validateInput(pattern, input),
+    )
+    const resolved = generated.map(resolve)
+    const destinations = new Set<string>()
+    for (const file of resolved) {
+      if (destinations.has(file.destination)) {
+        throw new PatternError(
+          `Duplicate Pattern destination: ${file.destination}`,
+        )
+      }
+      destinations.add(file.destination)
+    }
+    const files = await Promise.all(
+      resolved.map(async (file): Promise<PatternPlanFile> => {
+        const before = await readTextFileState(
+          environment.storage,
+          file.destination,
+        )
+        return Object.freeze({
+          ...file,
+          before,
+          status: status(before, file.content, conflicts),
+        })
+      }),
+    )
+    return Object.freeze({
+      pattern: id,
+      conflicts,
+      files: Object.freeze(files),
+    })
+  }
+
+  const apply: PatternInstaller["apply"] = async (patternPlan) => {
+    canonicalPatternId(patternPlan.pattern)
+    conflictPolicy(patternPlan.conflicts)
+    for (const file of patternPlan.files) {
+      const expected = status(file.before, file.content, patternPlan.conflicts)
+      if (file.status !== expected) {
+        throw new PatternError(`Invalid Pattern plan: ${file.destination}`)
+      }
+    }
+    const conflicts = patternPlan.files.filter(
+      (file) => file.status === "conflict",
+    )
+    if (patternPlan.conflicts === "error" && conflicts.length) {
+      throw new PatternError(
+        `Pattern ${patternPlan.pattern} conflicts with existing files: ${conflicts
+          .map((file) => file.destination)
+          .join(", ")}`,
+      )
+    }
+    const writes = patternPlan.files.filter(
+      (file) => file.status === "create" || file.status === "replace",
+    )
+    const resolved = writes.map((file) => {
+      const current = resolve({
+        root: file.root,
+        path: file.path,
+        content: file.content,
+      })
+      if (current.destination !== file.destination) {
+        throw new PatternError(`Invalid Pattern plan: ${file.destination}`)
+      }
+      return { ...file, destination: current.destination }
+    })
+    await Promise.all(
+      resolved.map(async (file) => {
+        let current: TextFileState
+        try {
+          current = await readTextFileState(
+            environment.storage,
+            file.destination,
+          )
+        } catch {
+          throw new PatternError(
+            `Pattern destination changed before install: ${file.destination}`,
+          )
+        }
+        if (!sameTextFileState(current, file.before)) {
+          throw new PatternError(
+            `Pattern destination changed before install: ${file.destination}`,
+          )
+        }
+      }),
+    )
+    const attempted: PatternPlanFile[] = []
+    try {
+      for (const file of resolved) {
+        attempted.push(file)
+        await environment.storage.writeText(file.destination, file.content)
+      }
+    } catch (error) {
+      const rollbackErrors = await rollback(environment.storage, attempted)
+      if (rollbackErrors.length) {
+        throw new AggregateError(
+          [error, ...rollbackErrors],
+          `Pattern ${patternPlan.pattern} install and rollback failed.`,
+        )
+      }
+      throw error
+    }
+    return patternPlan
+  }
+
+  const install: PatternInstaller["install"] = async (
+    pattern,
+    input,
+    options,
+  ) => {
+    const patternPlan = await plan(pattern, input, options)
+    return apply(patternPlan)
+  }
+
+  return Object.freeze({ plan, apply, install })
+}

package/perf.ts

@@ -0,0 +1,88 @@
+export type PerfRecord = {
+  name: string
+  count: number
+  totalMs: number
+  maxMs: number
+  lastMs: number
+  maxLabel?: string
+}
+
+export class Perf {
+  readonly records = new Map<string, PerfRecord>()
+
+  measure<T>(name: string, fn: () => T, label?: string): T {
+    const start = performance.now()
+    try {
+      return fn()
+    } finally {
+      this.add(name, performance.now() - start, label)
+    }
+  }
+
+  async measureAsync<T>(
+    name: string,
+    fn: () => Promise<T>,
+    label?: string,
+  ): Promise<T> {
+    const start = performance.now()
+    try {
+      return await fn()
+    } finally {
+      this.add(name, performance.now() - start, label)
+    }
+  }
+
+  /** Record an externally measured duration under a span name. */
+  record(name: string, ms: number, label?: string) {
+    this.add(name, ms, label)
+  }
+
+  snapshot(): PerfRecord[] {
+    return [...this.records.values()]
+  }
+
+  format() {
+    const rows = this.snapshot()
+    if (!rows.length) return ""
+    const nameWidth = Math.max(...rows.map((row) => row.name.length))
+    const countWidth = Math.max(
+      ...rows.map((row) => String(row.count).length),
+    )
+    return rows
+      .map((row) => {
+        const name = row.name.padEnd(nameWidth)
+        const count = `n=${row.count}`.padEnd(countWidth + 2)
+        const total = `${row.totalMs.toFixed(1)} ms`
+        const max = `max=${row.maxMs.toFixed(1)} ms`
+        const label = row.maxLabel ? `  ${row.maxLabel}` : ""
+        return `${name}  ${count}  ${total}  ${max}${label}`
+      })
+      .join("\n")
+  }
+
+  reset() {
+    this.records.clear()
+  }
+
+  private add(name: string, ms: number, label?: string) {
+    const current = this.records.get(name)
+    if (!current) {
+      this.records.set(name, {
+        name,
+        count: 1,
+        totalMs: ms,
+        maxMs: ms,
+        lastMs: ms,
+        maxLabel: label,
+      })
+      return
+    }
+    current.count += 1
+    current.totalMs += ms
+    current.lastMs = ms
+    if (ms >= current.maxMs) {
+      current.maxMs = ms
+      current.maxLabel = label
+    }
+  }
+}

package/plugins/actor-path.ts

@@ -0,0 +1,43 @@
+import type { Plugin } from "./types.ts"
+import { escapeHtml } from "../util.ts"
+
+export function ActorPathPlugin(): Plugin {
+  return {
+    id: "actor-path",
+    // Rewrite Home-relative paths only after a Principal has been admitted.
+    streamSelectors({ principal, source }) {
+      const actor = principal.type === "actor" ? principal.actor : undefined
+      return {
+        "[href^='~/']": {
+          element(el) {
+            const href = el.getAttribute("href")
+            if (!href?.startsWith("~/")) return
+            if (actor) el.setAttribute("href", `${actor.home}/${href.slice(2)}`)
+            else el.removeAttribute("href")
+          },
+        },
+        "form[action^='~/']": {
+          element(el) {
+            const action = el.getAttribute("action")
+            if (!action?.startsWith("~/")) return
+            if (actor)
+              el.setAttribute("action", `${actor.home}/${action.slice(2)}`)
+            else el.remove()
+          },
+        },
+        'form[action^="/actions/"]': {
+          element(el) {
+            if (!actor) {
+              el.remove()
+              return
+            }
+            el.prepend(
+              `<input type="hidden" name="_target" value="${escapeHtml(source.id)}" />`,
+              { html: true },
+            )
+          },
+        },
+      }
+    },
+  }
+}

package/plugins/actor-profile.ts

@@ -0,0 +1,55 @@
+import type { Plugin } from "./types.ts"
+import { isActorSource } from "../authority/actors.ts"
+
+export function actorProfileDependency(actorId: string) {
+  return {
+    type: "plugin" as const,
+    plugin: "actor-profile",
+    key: actorId,
+  }
+}
+
+export function ActorProfilePlugin(): Plugin {
+  return {
+    id: "actor-profile",
+    invalidate({ before, after }) {
+      const actor = after ?? before
+      if (!actor || !isActorSource(actor)) return
+      return { dependencies: [actorProfileDependency(actor.id)] }
+    },
+    streamSelectors({ principal }, app) {
+      return {
+        "[data-pmx-profile-name]": {
+          element(element) {
+            const id = element.getAttribute("data-pmx-profile-name") ?? ""
+            const profile = app.actors.profile(id)
+            element.removeAttribute("data-pmx-profile-name")
+            if (profile) element.setInnerContent(profile.name)
+            else element.remove()
+          },
+        },
+        "[data-pmx-profile-avatar]": {
+          element(element) {
+            const id = element.getAttribute("data-pmx-profile-avatar") ?? ""
+            const profile = app.actors.profile(id)
+            element.removeAttribute("data-pmx-profile-avatar")
+            if (profile?.avatar) element.setAttribute("src", profile.avatar)
+            else element.remove()
+          },
+        },
+        "[data-pmx-owner]": {
+          element(element) {
+            const owner = element.getAttribute("data-pmx-owner")
+            const actor =
+              principal.type === "actor" ? principal.actor : undefined
+            const allowed =
+              actor?.id === owner ||
+              (actor?.type === "user" && actor.role === "staff")
+            element.removeAttribute("data-pmx-owner")
+            if (!allowed) element.remove()
+          },
+        },
+      }
+    },
+  }
+}

package/plugins/agent-browsing.ts

@@ -0,0 +1,183 @@
+import { deriveSourceMeta, type Source } from "../source/index.ts"
+import { isPageSource, publicPath } from "../server/router.ts"
+import { AGENT_BROWSING_PLUGIN_ID } from "../server/protocols.ts"
+import { escapeHtml } from "../util.ts"
+import {
+  route,
+  type Plugin,
+  type ServerContext,
+  type StreamHandler,
+} from "./types.ts"
+
+const PUBLIC_CACHE = "public, max-age=300"
+const NO_STREAM_SELECTORS: Record<string, StreamHandler> = Object.freeze({})
+
+function hasPublicBacklink(source: Source, ctx: ServerContext) {
+  return ctx.graph.linksTo(source.path).some((edge) => {
+    if (edge.from === source.path) return false
+    const origin = ctx.source(edge.from)
+    return origin != null && ctx.isPublic(origin)
+  })
+}
+
+function discoverablePages(ctx: ServerContext) {
+  return ctx
+    .sources()
+    .filter((source) => {
+      if (!isPageSource(source) || !ctx.isPublic(source)) return false
+      if (ctx.resolve(publicPath(source)) !== source) return false
+      return publicPath(source) === "/" || hasPublicBacklink(source, ctx)
+    })
+    .sort((left, right) => {
+      const leftPath = publicPath(left)
+      const rightPath = publicPath(right)
+      return leftPath < rightPath ? -1 : leftPath > rightPath ? 1 : 0
+    })
+}
+
+function publicationBasePath(ctx: ServerContext) {
+  const suffix = `/${ctx.path}`
+  if (!ctx.url.pathname.endsWith(suffix)) return "/"
+  return ctx.url.pathname.slice(0, -suffix.length) || "/"
+}
+
+function mountedPath(ctx: ServerContext, pathname: string) {
+  const basePath = publicationBasePath(ctx)
+  if (basePath === "/") return pathname
+  return pathname === "/" ? basePath : `${basePath}${pathname}`
+}
+
+function absoluteUrl(ctx: ServerContext, pathname: string) {
+  return new URL(mountedPath(ctx, pathname), ctx.url.origin).href
+}
+
+function markdownText(value: string) {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll("[", "\\[")
+    .replaceAll("]", "\\]")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+function llmsTxt(ctx: ServerContext) {
+  const pages = discoverablePages(ctx)
+  const home = pages.find((source) => publicPath(source) === "/") ?? pages[0]
+  const homeMeta = home ? deriveSourceMeta(home) : undefined
+  const title = markdownText(homeMeta?.title || "PathMX")
+  const lines = [
+    `# ${title}`,
+    "",
+    ...(homeMeta?.description
+      ? [`> ${markdownText(homeMeta.description)}`, ""]
+      : []),
+    "## When to use this site",
+    "",
+    "Use this PathMX site to read, navigate, or cite its public Sources. The listed links return the authored Markdown representation directly. Use the sitemap for the canonical HTML URL index.",
+    "",
+    "## Public pages",
+    "",
+  ]
+
+  if (!pages.length) lines.push("No public pages are currently available.")
+  for (const source of pages) {
+    const meta = deriveSourceMeta(source)
+    const description = meta.description
+      ? ` — ${markdownText(meta.description)}`
+      : ""
+    lines.push(
+      `- [${markdownText(meta.title)}](${absoluteUrl(ctx, source.path)})${description}`,
+    )
+  }
+
+  lines.push("", `- [XML sitemap](${absoluteUrl(ctx, "/sitemap.xml")})`, "")
+  return lines.join("\n")
+}
+
+function robotsTxt(ctx: ServerContext) {
+  const basePath = publicationBasePath(ctx)
+  const root = basePath === "/" ? "/" : `${basePath}/`
+  return [
+    "User-agent: *",
+    `Allow: ${root}`,
+    `Disallow: ${mountedPath(ctx, "/.pmx/")}`,
+    `Disallow: ${mountedPath(ctx, "/actions/")}`,
+    `Disallow: ${mountedPath(ctx, "/api/runtime/")}`,
+    "",
+    `Host: ${ctx.url.origin}`,
+    `Sitemap: ${absoluteUrl(ctx, "/sitemap.xml")}`,
+    "",
+  ].join("\n")
+}
+
+function escapeXml(value: string) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+}
+
+function sitemapXml(ctx: ServerContext) {
+  const urls = discoverablePages(ctx)
+    .map(
+      (source) =>
+        `  <url><loc>${escapeXml(absoluteUrl(ctx, publicPath(source)))}</loc></url>`,
+    )
+    .join("\n")
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    urls,
+    "</urlset>",
+    "",
+  ].join("\n")
+}
+
+function publicText(body: string, contentType: string) {
+  return new Response(body, {
+    headers: {
+      "Content-Type": contentType,
+      "Cache-Control": PUBLIC_CACHE,
+    },
+  })
+}
+
+/** Public discovery documents for LLMs, crawlers, and other browsing agents. */
+export function AgentBrowsingPlugin(): Plugin {
+  return {
+    id: AGENT_BROWSING_PLUGIN_ID,
+    name: "AgentBrowsingPlugin",
+    routes: [
+      route.get("llms.txt", (ctx) =>
+        publicText(llmsTxt(ctx), "text/plain; charset=utf-8"),
+      ),
+      route.get("robots.txt", (ctx) =>
+        publicText(robotsTxt(ctx), "text/plain; charset=utf-8"),
+      ),
+      route.get("sitemap.xml", (ctx) =>
+        publicText(sitemapXml(ctx), "application/xml; charset=utf-8"),
+      ),
+    ],
+    publish(ctx) {
+      ctx.route("/llms.txt")
+      ctx.route("/robots.txt")
+      ctx.route("/sitemap.xml")
+    },
+    streamSelectors({ source }, app) {
+      if (!app.sources.isPage(source)) return NO_STREAM_SELECTORS
+      const href = escapeHtml(source.path)
+      return {
+        head: {
+          element(element) {
+            element.prepend(
+              `<link rel="alternate" type="text/markdown" href="${href}">`,
+              { html: true },
+            )
+          },
+        },
+      }
+    },
+  }
+}

package/plugins/app-component.ts

@@ -0,0 +1,23 @@
+import { stringifyHtml } from "../html.ts"
+import { stampHtmlRoot } from "../view/syntax.ts"
+import type { ViewComponent } from "./types.ts"
+
+/** @internal Browser-owned roots are opaque to document morphing. */
+export const APP_COMPONENT_ROOT_ATTRIBUTE = "data-pmx-app"
+
+/** Define a browser-owned View Component whose client is bundled when authored. */
+export function defineAppComponent<Compiled = undefined>(
+  definition: ViewComponent<Compiled> & Readonly<{ client: string | URL }>,
+): ViewComponent<Compiled> {
+  const { render, ...component } = definition
+  return {
+    ...component,
+    async render(use, compiled, ctx, app) {
+      return stampHtmlRoot(
+        stringifyHtml(await render(use, compiled, ctx, app)),
+        { [APP_COMPONENT_ROOT_ATTRIBUTE]: "" },
+        app.html.rewrite,
+      )
+    },
+  }
+}