livemark 0.25.0 → 0.27.0

package/source/helpers/agent-skills.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto"
+import { globSync, readFileSync } from "node:fs"
+import { resolve, sep } from "node:path"
+import { parse } from "yaml"
+import { z } from "zod"
+
+const SKILLS_SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json"
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+const SkillFrontmatter = z.object({
+  name: z
+    .string()
+    .max(64)
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z.string().min(1).max(1024),
+})
+
+/** A `SKILL.md` published for agents, with the raw bytes its digest covers. */
+export interface AgentSkill {
+  name: string
+  description: string
+  source: Buffer
+}
+
+/** Read every `SKILL.md` the `skills` globs match, in a stable order. */
+export function loadAgentSkills(props: { root: string; patterns: string[] }) {
+  // Windows globs with `\`, which would leak into messages and change the sort.
+  return globSync(props.patterns, { cwd: props.root })
+    .map(file => file.split(sep).join("/"))
+    .sort()
+    .map(file => {
+      const source = readFileSync(resolve(props.root, file))
+      const frontmatter = FRONTMATTER_RE.exec(source.toString("utf-8"))?.[1] ?? ""
+      const parsed = SkillFrontmatter.safeParse(parse(frontmatter))
+      if (!parsed.success) {
+        throw new Error(
+          `${file}: a published skill needs a frontmatter \`name\` (lowercase, hyphenated) and \`description\``,
+        )
+      }
+      return { ...parsed.data, source }
+    })
+}
+
+/** Where a skill is published inside the build output (no base). */
+export function buildSkillFileName(name: string) {
+  return `.well-known/agent-skills/${name}/SKILL.md`
+}
+
+/** Render the Agent Skills discovery index (v0.2.0) for the published skills. */
+export function renderSkillsIndex(props: { skills: AgentSkill[]; base?: string }) {
+  const skills = props.skills.map(skill => ({
+    name: skill.name,
+    type: "skill-md",
+    description: skill.description,
+    url: `${props.base ?? ""}/${buildSkillFileName(skill.name)}`,
+    digest: `sha256:${createHash("sha256").update(skill.source).digest("hex")}`,
+  }))
+  return `${JSON.stringify({ $schema: SKILLS_SCHEMA, skills }, null, 2)}\n`
+}

package/source/helpers/agent-skills.unit.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto"
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, it } from "vite-plus/test"
+import { temporaryDirectory } from "tempy"
+import { loadAgentSkills, renderSkillsIndex } from "./agent-skills.ts"
+
+function writeSkill(root: string, dir: string, source: string) {
+  mkdirSync(join(root, "skills", dir), { recursive: true })
+  writeFileSync(join(root, "skills", dir, "SKILL.md"), source)
+}
+
+describe("loadAgentSkills", () => {
+  it("reads name and description from each matched SKILL.md", () => {
+    const root = temporaryDirectory()
+    writeSkill(root, "b", "---\nname: beta\ndescription: >\n  Folded\n  text\n---\n# B\n")
+    writeSkill(root, "a", "---\nname: alpha\ndescription: First\n---\n# A\n")
+    const skills = loadAgentSkills({ root, patterns: ["skills/*/SKILL.md"] })
+    expect(skills.map(s => [s.name, s.description])).toEqual([
+      ["alpha", "First"],
+      ["beta", "Folded text\n"],
+    ])
+  })
+
+  it("rejects a skill whose name agents cannot address", () => {
+    const root = temporaryDirectory()
+    writeSkill(root, "a", "---\nname: Not Valid\ndescription: First\n---\n")
+    expect(() => loadAgentSkills({ root, patterns: ["skills/*/SKILL.md"] })).toThrow(
+      "skills/a/SKILL.md",
+    )
+  })
+})
+
+describe("renderSkillsIndex", () => {
+  it("publishes each skill with a digest of its exact bytes", () => {
+    const source = Buffer.from("---\nname: alpha\ndescription: First\n---\n")
+    const index = JSON.parse(
+      renderSkillsIndex({
+        skills: [{ name: "alpha", description: "First", source }],
+        base: "/repo",
+      }),
+    )
+    expect(index).toEqual({
+      $schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+      skills: [
+        {
+          name: "alpha",
+          type: "skill-md",
+          description: "First",
+          url: "/repo/.well-known/agent-skills/alpha/SKILL.md",
+          digest: `sha256:${createHash("sha256").update(source).digest("hex")}`,
+        },
+      ],
+    })
+  })
+})

package/source/helpers/article-search.tsx

@@ -0,0 +1,192 @@
+import { useState, useRef, useCallback, useMemo } from "react"
+import { useNavigate } from "@tanstack/react-router"
+import { create, insertMultiple, search } from "@orama/orama"
+import { sortedArticles } from "../content/article.ts"
+import { resolveArticleIcon } from "./article-icon.ts"
+import { buildHighlightPattern, findTextMatches } from "./search-highlight.ts"
+import { CommandGroup, CommandItem } from "../elements/command.tsx"
+
+interface SearchResult {
+  title: string
+  path: string
+  icon?: string
+  snippet: string
+  group: string
+}
+
+export function useArticleSearch() {
+  const [results, setResults] = useState<SearchResult[]>([])
+  const [query, setQuery] = useState("")
+  const dbRef = useRef<Awaited<ReturnType<typeof create>> | null>(null)
+  const navigate = useNavigate()
+
+  const ensureIndex = useCallback(async () => {
+    if (dbRef.current) return dbRef.current
+    const db = await create({
+      schema: {
+        title: "string",
+        description: "string",
+        searchText: "string",
+      },
+    })
+    await insertMultiple(
+      db,
+      sortedArticles.map(a => ({
+        title: a.title,
+        description: a.description ?? "",
+        searchText: a.searchText,
+      })),
+    )
+    dbRef.current = db
+    return db
+  }, [])
+
+  const searchArticles = useCallback(
+    async (term: string) => {
+      setQuery(term)
+      if (!term.trim()) {
+        setResults([])
+        return
+      }
+      const db = await ensureIndex()
+      const hits = await search(db, {
+        term,
+        properties: ["title", "description", "searchText"],
+        tolerance: 1,
+        boost: { title: 3, description: 2 },
+      })
+      setResults(
+        hits.hits.map(hit => {
+          const article = sortedArticles.find(a => a.title === hit.document.title)
+          if (!article)
+            return toResult(
+              {
+                ...sortedArticles[0],
+                title: hit.document.title,
+                path: "",
+                searchText: hit.document.description,
+                description: hit.document.description,
+                icon: "",
+              },
+              term,
+            )
+          return toResult(article, term)
+        }),
+      )
+    },
+    [ensureIndex],
+  )
+
+  const selectArticle = useCallback(
+    (path: string) => {
+      setQuery("")
+      setResults([])
+      navigate({
+        to: "/$",
+        params: { _splat: path.replace(/^\/|\/$/g, "") },
+        search: { highlight: query.trim() || undefined },
+      })
+    },
+    [navigate, query],
+  )
+
+  const grouped = useMemo(() => {
+    const groups = new Map<string, SearchResult[]>()
+    for (const r of results) {
+      const list = groups.get(r.group) ?? []
+      list.push(r)
+      groups.set(r.group, list)
+    }
+    return groups
+  }, [results])
+
+  return { query, grouped, searchArticles, selectArticle }
+}
+
+export function SearchResultGroups(props: {
+  query: string
+  grouped: Map<string, SearchResult[]>
+  onSelect: (path: string) => void
+}) {
+  return [...props.grouped.entries()].map(([group, items]) => (
+    <CommandGroup key={group} heading={group}>
+      {items.map(result => {
+        const Icon = resolveArticleIcon(result.icon)
+        return (
+          <CommandItem
+            key={result.path}
+            value={result.path}
+            onSelect={() => props.onSelect(result.path)}
+            className="py-2.5"
+          >
+            {Icon && <Icon className="size-5 shrink-0 mt-0.5 self-start opacity-60" />}
+            <div className="flex flex-col gap-0.5 min-w-0">
+              <span className="text-base font-medium">{result.title}</span>
+              {result.snippet && (
+                <span className="text-sm text-muted-foreground line-clamp-1">
+                  <HighlightedText text={result.snippet} term={props.query} />
+                </span>
+              )}
+            </div>
+          </CommandItem>
+        )
+      })}
+    </CommandGroup>
+  ))
+}
+
+function toResult(article: (typeof sortedArticles)[number], term: string): SearchResult {
+  return {
+    title: article.title,
+    path: article.path,
+    icon: article.icon,
+    snippet: term
+      ? extractSnippet(article.searchText, term)
+      : (article.description ?? ""),
+    group: groupFor(article.path),
+  }
+}
+
+function groupFor(pathname: string) {
+  const segments = pathname.replace(/^\/|\/$/g, "").split("/")
+  if (segments.length <= 2) return "Pages"
+  return segments
+    .slice(1, -1)
+    .map(s =>
+      s
+        .split("-")
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" "),
+    )
+    .join(" › ")
+}
+
+function extractSnippet(text: string, term: string) {
+  const pattern = buildHighlightPattern(term)
+  const [match] = pattern ? findTextMatches(text, pattern) : []
+  if (!match) return text.slice(0, 120)
+  const [matchStart, matchEnd] = match
+  const start = Math.max(0, matchStart - 40)
+  const end = Math.min(text.length, matchEnd + 80)
+  const prefix = start > 0 ? "…" : ""
+  const suffix = end < text.length ? "…" : ""
+  return `${prefix}${text.slice(start, end)}${suffix}`
+}
+
+function HighlightedText(props: { text: string; term: string }) {
+  const pattern = buildHighlightPattern(props.term)
+  if (!pattern) return <>{props.text}</>
+  const parts: React.ReactNode[] = []
+  let cursor = 0
+  for (const [start, end] of findTextMatches(props.text, pattern)) {
+    parts.push(props.text.slice(cursor, start))
+    parts.push(
+      <span key={start} className="text-foreground font-medium">
+        {props.text.slice(start, end)}
+      </span>,
+    )
+    cursor = end
+  }
+  parts.push(props.text.slice(cursor))
+  return <>{parts}</>
+}

package/source/helpers/article.ts

@@ -50,3 +50,20 @@ export function flattenArticleTree(nodes: ArticleNode[]) {
   }
   return result
 }
+
+/** Sort comparator on frontmatter `order`: positive ascending, then unordered,
+ *  then negative (so `order: -1` lands last) */
+export function compareArticleOrder(a: { order?: number }, b: { order?: number }) {
+  return orderKey(a.order) - orderKey(b.order)
+}
+
+/** Sort comparator putting the newest `date` first, as blog and changelog list */
+export function compareArticleDate(a: { date?: string }, b: { date?: string }) {
+  return new Date(b.date ?? 0).getTime() - new Date(a.date ?? 0).getTime()
+}
+
+function orderKey(order?: number) {
+  if (order === undefined) return Number.MAX_SAFE_INTEGER / 2
+  if (order < 0) return Number.MAX_SAFE_INTEGER + order
+  return order
+}

package/source/helpers/dependency-dir.ts

@@ -0,0 +1,20 @@
+import { existsSync, readdirSync, realpathSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+/**
+ * Locate the directory holding livemark's own dependencies, which the project's target
+ * links to as its `node_modules`.
+ */
+export function resolveDependencyDir(sourceDir: string) {
+  const packageDir = realpathSync(dirname(sourceDir))
+  const parent = dirname(packageDir)
+  const nested = join(packageDir, "node_modules")
+  // pnpm gives an installed package a `.bin`-only `node_modules`; its deps sit beside it
+  // in the store. Only real packages there (a checkout, npm's conflict copies) count.
+  if (hasPackages(nested) || basename(parent) !== "node_modules") return nested
+  return parent
+}
+
+function hasPackages(dir: string) {
+  return existsSync(dir) && readdirSync(dir).some(name => !name.startsWith("."))
+}

package/source/helpers/dependency-dir.unit.ts

@@ -0,0 +1,39 @@
+import { realpathSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { resolveDependencyDir } from "./dependency-dir.ts"
+
+describe("resolveDependencyDir", () => {
+  it("uses the store dir beside an isolated install", () =>
+    temporaryDirectoryTask(async root => {
+      const store = join(root, ".pnpm/livemark@1.0.0/node_modules")
+      await mkdir(join(store, "livemark/source"), { recursive: true })
+      await mkdir(join(store, "livemark/node_modules/.bin"), { recursive: true })
+
+      expect(resolveDependencyDir(join(store, "livemark/source"))).toBe(
+        realpathSync(store),
+      )
+    }))
+
+  it("uses the package's own node_modules when it has one", () =>
+    temporaryDirectoryTask(async root => {
+      const packageDir = join(root, "node_modules/livemark")
+      await mkdir(join(packageDir, "source"), { recursive: true })
+      await mkdir(join(packageDir, "node_modules/zod"), { recursive: true })
+
+      expect(resolveDependencyDir(join(packageDir, "source"))).toBe(
+        join(realpathSync(packageDir), "node_modules"),
+      )
+    }))
+
+  it("uses the checkout's node_modules outside an install", () =>
+    temporaryDirectoryTask(async root => {
+      await mkdir(join(root, "livemark/source"), { recursive: true })
+
+      expect(resolveDependencyDir(join(root, "livemark/source"))).toBe(
+        join(realpathSync(root), "livemark/node_modules"),
+      )
+    }))
+})

package/source/helpers/head.ts

@@ -0,0 +1,105 @@
+import type * as React from "react"
+import type { WebsiteConfig } from "../models/config.ts"
+import { faviconType } from "./favicon.ts"
+import { prefixUrl } from "./prefix-url.ts"
+import { buildThemeScript } from "./theme.ts"
+
+/** Site-wide `<head>` tags the root route renders on every page. */
+export interface RootHead {
+  meta: Array<React.JSX.IntrinsicElements["meta"]>
+  links: Array<React.JSX.IntrinsicElements["link"]>
+  scripts: Array<React.JSX.IntrinsicElements["script"]>
+}
+
+export function buildRootHead(props: {
+  config: WebsiteConfig
+  defaultFavicon: string
+  stylesheets: string[]
+}) {
+  const config = props.config
+  const favicon = prefixUrl(
+    config.favicon ?? config.logo ?? props.defaultFavicon,
+    config.base,
+  )
+  const feedLinks = config.site
+    ? (config.sections ?? [])
+        .filter(s => s.type === "blog")
+        .map(s => ({
+          rel: "alternate",
+          type: "application/rss+xml",
+          title: `${s.siteTitle ?? s.title} RSS Feed`,
+          href: prefixUrl(`${s.prefix}rss.xml`, config.base),
+        }))
+    : []
+  return {
+    meta: [
+      { charSet: "utf-8" },
+      { title: config.title },
+      { name: "description", content: config.description },
+      { property: "og:title", content: config.title },
+      { property: "og:description", content: config.description },
+      { property: "og:site_name", content: config.title },
+      { property: "og:type", content: "website" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      ...(config.head?.meta ?? []),
+    ],
+    links: [
+      { rel: "icon", href: favicon, type: faviconType(favicon) },
+      { rel: "shortcut icon", href: favicon, type: faviconType(favicon) },
+      ...props.stylesheets.map(href => ({ rel: "stylesheet", href })),
+      ...feedLinks,
+      ...(config.head?.links ?? []),
+    ],
+    scripts: [{ children: buildThemeScript() }, ...(config.head?.scripts ?? [])],
+  }
+}
+
+export function buildPageHead(props: {
+  config: WebsiteConfig
+  path: string
+  title?: string
+  description?: string
+  image?: string
+  isArticle?: boolean
+}) {
+  const site = props.config.site?.replace(/\/+$/, "")
+  const url = site ? buildAbsoluteUrl(site, props.config.base, props.path) : undefined
+  const image =
+    site && props.image
+      ? buildAbsoluteUrl(site, props.config.base, props.image)
+      : undefined
+  return {
+    meta: [
+      ...(props.title
+        ? [{ title: props.title }, { property: "og:title", content: props.title }]
+        : []),
+      ...(props.description
+        ? [
+            { name: "description", content: props.description },
+            { property: "og:description", content: props.description },
+          ]
+        : []),
+      ...(props.isArticle ? [{ property: "og:type", content: "article" }] : []),
+      ...(url ? [{ property: "og:url", content: url }] : []),
+      ...(image ? [{ property: "og:image", content: image }] : []),
+    ],
+    links: [
+      ...(url ? [{ rel: "canonical", href: url }] : []),
+      ...(props.isArticle
+        ? [
+            {
+              rel: "alternate",
+              type: "text/markdown",
+              href: prefixUrl(`${props.path}index.md`, props.config.base),
+            },
+          ]
+        : []),
+    ],
+  }
+}
+
+function buildAbsoluteUrl(site: string, base: string | undefined, url: string) {
+  const prefixed = prefixUrl(url, base)
+  if (!prefixed.startsWith("/") || prefixed.startsWith("//")) return prefixed
+  return `${site}${prefixed}`
+}

package/source/helpers/head.unit.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vite-plus/test"
+import type { WebsiteConfig } from "../models/config.ts"
+import { buildPageHead, buildRootHead } from "./head.ts"
+
+const config: WebsiteConfig = { title: "Docs", description: "Blurb" }
+
+describe("buildRootHead", () => {
+  it("builds the default site tags", () => {
+    const head = buildRootHead({
+      config,
+      defaultFavicon: "/logo.svg",
+      stylesheets: ["/a.css"],
+    })
+    expect(head.meta).toContainEqual({ property: "og:title", content: "Docs" })
+    expect(head.links).toContainEqual({
+      rel: "icon",
+      href: "/logo.svg",
+      type: "image/svg+xml",
+    })
+    expect(head.links).toContainEqual({ rel: "stylesheet", href: "/a.css" })
+    expect(head.scripts).toHaveLength(1)
+  })
+
+  it("appends config head tags after the defaults", () => {
+    const head = buildRootHead({
+      config: {
+        ...config,
+        head: {
+          meta: [{ property: "og:type", content: "book" }],
+          links: [{ rel: "me", href: "https://x.com/me" }],
+          scripts: [{ src: "https://cdn.example.com/a.js" }],
+        },
+      },
+      defaultFavicon: "/logo.svg",
+      stylesheets: [],
+    })
+    expect(head.meta.at(-1)).toEqual({ property: "og:type", content: "book" })
+    expect(head.links.at(-1)).toEqual({ rel: "me", href: "https://x.com/me" })
+    expect(head.scripts.at(-1)).toEqual({ src: "https://cdn.example.com/a.js" })
+  })
+
+  it("links blog feeds only when site is set", () => {
+    const sections: WebsiteConfig["sections"] = [
+      { type: "blog", title: "Blog", prefix: "/blog/", position: "header" },
+    ]
+    const withoutSite = buildRootHead({
+      config: { ...config, sections },
+      defaultFavicon: "/logo.svg",
+      stylesheets: [],
+    })
+    const withSite = buildRootHead({
+      config: { ...config, sections, site: "https://example.com", base: "/repo" },
+      defaultFavicon: "/logo.svg",
+      stylesheets: [],
+    })
+    expect(withoutSite.links.some(l => l.rel === "alternate")).toBe(false)
+    expect(withSite.links).toContainEqual({
+      rel: "alternate",
+      type: "application/rss+xml",
+      title: "Blog RSS Feed",
+      href: "/repo/blog/rss.xml",
+    })
+  })
+})
+
+describe("buildPageHead", () => {
+  it("emits title, description and article type", () => {
+    const head = buildPageHead({
+      config,
+      path: "/guide/",
+      title: "Guide",
+      description: "How to",
+      isArticle: true,
+    })
+    expect(head.meta).toEqual([
+      { title: "Guide" },
+      { property: "og:title", content: "Guide" },
+      { name: "description", content: "How to" },
+      { property: "og:description", content: "How to" },
+      { property: "og:type", content: "article" },
+    ])
+    expect(head.links).toEqual([
+      { rel: "alternate", type: "text/markdown", href: "/guide/index.md" },
+    ])
+  })
+
+  it("adds absolute url, canonical and image when site is set", () => {
+    const head = buildPageHead({
+      config: { ...config, site: "https://example.com/", base: "/repo" },
+      path: "/guide/",
+      image: "/repo/assets/cover.png",
+    })
+    expect(head.meta).toEqual([
+      { property: "og:url", content: "https://example.com/repo/guide/" },
+      { property: "og:image", content: "https://example.com/repo/assets/cover.png" },
+    ])
+    expect(head.links).toEqual([
+      { rel: "canonical", href: "https://example.com/repo/guide/" },
+    ])
+  })
+
+  it("keeps an already absolute image", () => {
+    const head = buildPageHead({
+      config: { ...config, site: "https://example.com" },
+      path: "/",
+      image: "https://cdn.example.com/cover.png",
+    })
+    expect(head.meta).toContainEqual({
+      property: "og:image",
+      content: "https://cdn.example.com/cover.png",
+    })
+  })
+
+  it("skips og:image without site", () => {
+    const head = buildPageHead({ config, path: "/", image: "/cover.png" })
+    expect(head.meta).toEqual([])
+  })
+})