livemark 0.7.2 → 0.8.0

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "livemark",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Livemark description",
   "license": "MIT",
   "author": "Evgeny Karev",
   "repository": "https://github.com/datisthq/livemark",
   "bin": {
-    "livemark": "./build/entrypoints/main.js"
+    "livemark": "./target/entrypoints/main.js"
   },
   "files": [
-    "build",
+    "target",
+    "source",
     "skills"
   ],
   "type": "module",
   "sideEffects": false,
-  "imports": {
-    "#*": "./*"
-  },
   "exports": {
-    ".": "./build/index.js",
-    "./components/*": "./build/website/components/*.tsx",
-    "./elements/*": "./build/website/elements/*.tsx",
-    "./styles/*": "./build/website/styles/*.css"
+    ".": "./target/index.js",
+    "./components/*": "./source/components/*.tsx",
+    "./elements/*": "./source/elements/*.tsx",
+    "./hooks/*": "./source/hooks/*.ts",
+    "./styles/*": "./source/styles/*.css",
+    "./utils/*": "./source/utils/*.ts"
   },
   "dependencies": {
     "@base-ui/react": "1.3.0",
@@ -113,11 +113,11 @@
     "pnpm": "^10.0.0"
   },
   "scripts": {
-    "build": "tsgo && rm -rf build/website && cp -r website build",
+    "build": "tsgo",
     "bump": "ncu -u",
-    "clean": "rm -rf pnpm-lock.yaml node_modules build",
-    "docs:build": "node entrypoints/main.ts build",
-    "docs:start": "node entrypoints/main.ts start",
+    "clean": "rm -rf pnpm-lock.yaml node_modules target",
+    "docs:build": "node source/entrypoints/main.ts build",
+    "docs:start": "node source/entrypoints/main.ts start",
     "format": "vp fmt",
     "lint": "vp fmt --check && vp lint",
     "release": "pnpm publish --access public --ignore-scripts --no-git-checks",

package/source/actions/changelog/build.ts

@@ -0,0 +1,245 @@
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { dirname, join, resolve } from "node:path"
+import slugify from "@sindresorhus/slugify"
+import type { Root, RootContent } from "mdast"
+import { toString as mdastToString } from "mdast-util-to-string"
+import remarkParse from "remark-parse"
+import remarkStringify from "remark-stringify"
+import { unified } from "unified"
+import { visit } from "unist-util-visit"
+import type { Config } from "../../models/config.ts"
+import type { ChangelogSection } from "../../models/section.ts"
+import { isGitHubUrl, parseGitHubRepo } from "../../helpers/changelog-source.ts"
+
+interface Release {
+  tag_name: string
+  name?: string | null
+  published_at?: string | null
+  body?: string | null
+  html_url?: string | null
+}
+
+interface CacheMeta {
+  etag: string
+  fetchedAt: string
+}
+
+interface ChangelogEntry {
+  slug: string
+  title: string
+  date?: string
+  body: string
+  sourceUrl?: string
+}
+
+const CACHE_DIR = ".livemark/cache/changelog"
+const META_FILE = ".livemark/cache/changelog.meta.json"
+
+const parser = unified().use(remarkParse)
+const stringifier = unified().use(remarkStringify, {
+  bullet: "-",
+  fences: true,
+  emphasis: "_",
+})
+
+export function cacheIncludeGlob() {
+  return `${CACHE_DIR}/**/*.md`
+}
+
+/** Build the per-version changelog cache files for a changelog section */
+export async function buildChangelog(
+  section: ChangelogSection,
+  config: Config,
+) {
+  const cacheDir = join(config.root, CACHE_DIR)
+  const metaPath = join(config.root, META_FILE)
+
+  const entries = isGitHubUrl(section.source)
+    ? await buildFromGitHub(section.source, metaPath, cacheDir)
+    : await buildFromLocal(section.source, config.root)
+
+  if (entries === undefined) return
+
+  await rm(cacheDir, { recursive: true, force: true })
+  await mkdir(cacheDir, { recursive: true })
+
+  for (const entry of entries) {
+    const markdown = wrapFrontmatter(entry, section)
+    await writeFile(join(cacheDir, `${entry.slug}.md`), markdown, "utf-8")
+  }
+}
+
+async function buildFromLocal(source: string, root: string) {
+  const filePath = resolve(root, source)
+  const body = await readFile(filePath, "utf-8")
+  return splitLocalChangelog(body)
+}
+
+/** Parse CHANGELOG.md into per-version entries using mdast */
+export function splitLocalChangelog(body: string): ChangelogEntry[] {
+  const tree = parser.parse(body) as Root
+  const entries: ChangelogEntry[] = []
+  let current: { heading: string; children: RootContent[] } | undefined
+
+  for (const child of tree.children) {
+    if (child.type === "heading" && child.depth === 2) {
+      if (current) entries.push(finalizeEntry(current))
+      current = { heading: mdastToString(child), children: [] }
+    } else if (current) {
+      current.children.push(child)
+    }
+  }
+  if (current) entries.push(finalizeEntry(current))
+  return entries
+}
+
+function finalizeEntry(input: {
+  heading: string
+  children: RootContent[]
+}): ChangelogEntry {
+  const versionMatch = input.heading.match(/^\[?([^\]\s]+)\]?/)
+  const version = versionMatch?.[1] ?? input.heading
+  const dateMatch = input.heading.match(/\d{4}-\d{2}-\d{2}/)
+  const body = renderEntryBody(input.children)
+  return {
+    slug: slugify(version),
+    title: version,
+    date: dateMatch?.[0],
+    body,
+  }
+}
+
+/** Serialize an entry's mdast children back to markdown */
+function renderEntryBody(children: RootContent[]) {
+  const root: Root = { type: "root", children }
+  return stringifier.stringify(root).trimEnd()
+}
+
+/** Drop the body's leading h1 (typically the conventional-changelog
+ * `# 0.7.2 (2026-04-25)` boilerplate that duplicates the article's title),
+ * shift h2–h6 up by one so subsection headings become h1 / h2 / …, and
+ * escape stray `<` outside code so MDX doesn't mistake them for JSX. */
+function processBody(body: string) {
+  const tree = parser.parse(body) as Root
+  visit(tree, "heading", node => {
+    if (node.depth > 1) node.depth = (node.depth - 1) as 1 | 2 | 3 | 4 | 5
+  })
+  if (tree.children[0]?.type === "heading" && tree.children[0].depth === 1) {
+    tree.children.shift()
+  }
+  return escapeMdxAngles(stringifier.stringify(tree).trimEnd())
+}
+
+/** Escape `<` to `\<` outside fenced code blocks and inline backtick spans
+ * so commit messages with placeholders like `<subdir>` don't get parsed as
+ * JSX by MDX. */
+function escapeMdxAngles(markdown: string) {
+  let inFence = false
+  return markdown
+    .split("\n")
+    .map(line => {
+      if (line.startsWith("```")) {
+        inFence = !inFence
+        return line
+      }
+      if (inFence) return line
+      return line.replace(/`[^`]*`|</g, match =>
+        match === "<" ? "\\<" : match,
+      )
+    })
+    .join("\n")
+}
+
+async function buildFromGitHub(
+  source: string,
+  metaPath: string,
+  cacheDir: string,
+): Promise<ChangelogEntry[] | undefined> {
+  const parsed = parseGitHubRepo(source)
+  if (!parsed) {
+    throw new Error(`Could not parse GitHub repo from source: ${source}`)
+  }
+
+  const url = `https://api.github.com/repos/${parsed.owner}/${parsed.repo}/releases?per_page=100`
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  }
+
+  const token = process.env.GITHUB_TOKEN
+  if (token) headers.Authorization = `Bearer ${token}`
+
+  const meta = await readMeta(metaPath)
+  const hasCache = await exists(cacheDir)
+  if (meta && hasCache) headers["If-None-Match"] = meta.etag
+
+  const res = await fetch(url, { headers })
+
+  if (res.status === 304) return undefined
+
+  if (!res.ok) {
+    const remaining = res.headers.get("x-ratelimit-remaining")
+    const reset = res.headers.get("x-ratelimit-reset")
+    const msg = `GitHub API ${res.status} ${res.statusText} (rate-limit remaining: ${remaining ?? "?"}, reset: ${reset ?? "?"})`
+    if (hasCache) {
+      console.warn(`${msg} — falling back to cached changelog`)
+      return undefined
+    }
+    throw new Error(msg)
+  }
+
+  const releases = (await res.json()) as Release[]
+  const etag = res.headers.get("etag")
+  if (etag) {
+    await mkdir(dirname(metaPath), { recursive: true })
+    await writeFile(
+      metaPath,
+      JSON.stringify(
+        { etag, fetchedAt: new Date().toISOString() } satisfies CacheMeta,
+        null,
+        2,
+      ),
+      "utf-8",
+    )
+  }
+
+  return releases.map(release => ({
+    slug: slugify(release.tag_name),
+    title: release.tag_name,
+    date: release.published_at ?? undefined,
+    body: (release.body ?? "").trim(),
+    sourceUrl: release.html_url ?? undefined,
+  }))
+}
+
+function wrapFrontmatter(entry: ChangelogEntry, section: ChangelogSection) {
+  const lines = [
+    "---",
+    `title: ${entry.title}`,
+    `path: ${section.prefix}${entry.slug}/`,
+  ]
+  if (entry.date) lines.push(`date: ${entry.date}`)
+  if (entry.sourceUrl) {
+    lines.push(`sourceUrl: ${entry.sourceUrl}`, "sourceAction: view")
+  }
+  lines.push("---", "", `# ${entry.title}`, "", processBody(entry.body))
+  return lines.join("\n")
+}
+
+async function readMeta(metaPath: string): Promise<CacheMeta | undefined> {
+  try {
+    const raw = await readFile(metaPath, "utf-8")
+    return JSON.parse(raw) as CacheMeta
+  } catch {
+    return undefined
+  }
+}
+
+async function exists(path: string) {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/source/actions/changelog/build.unit.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vite-plus/test"
+import { splitLocalChangelog } from "./build.ts"
+
+describe("splitLocalChangelog", () => {
+  it("splits by h2 headings", () => {
+    const input = `# Changelog
+
+## [0.2.0] - 2026-04-15
+
+### Added
+
+- Foo
+
+## [0.1.0] - 2026-04-10
+
+Initial release.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries).toHaveLength(2)
+    expect(entries[0]?.title).toBe("0.2.0")
+    expect(entries[0]?.date).toBe("2026-04-15")
+    expect(entries[0]?.slug).toBe("0-2-0")
+    expect(entries[1]?.title).toBe("0.1.0")
+    expect(entries[1]?.date).toBe("2026-04-10")
+  })
+
+  it("preserves h3 heading structure in body", () => {
+    const input = `## 1.0.0
+
+### Added
+
+- Thing one
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries[0]?.body).toContain("### Added")
+    expect(entries[0]?.body).toContain("- Thing one")
+  })
+
+  it("ignores ## inside fenced code blocks", () => {
+    const input = `## 1.0.0
+
+Some prose.
+
+\`\`\`md
+## Not a real version heading
+\`\`\`
+
+## 0.9.0
+
+Older.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries).toHaveLength(2)
+    expect(entries[0]?.title).toBe("1.0.0")
+    expect(entries[0]?.body).toContain("Not a real version heading")
+    expect(entries[1]?.title).toBe("0.9.0")
+  })
+
+  it("handles bare version headings without brackets or date", () => {
+    const input = `## v1.2.3
+
+Release notes.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries[0]?.title).toBe("v1.2.3")
+    expect(entries[0]?.slug).toBe("v1-2-3")
+    expect(entries[0]?.date).toBeUndefined()
+  })
+})

package/source/actions/config/define.ts

@@ -0,0 +1,11 @@
+import type { z } from "zod"
+import { UserConfig } from "../../models/config.ts"
+
+/**
+ * Validate and fill defaults for a partial config object.
+ */
+export function defineConfig(
+  input: z.input<typeof UserConfig>,
+): z.output<typeof UserConfig> {
+  return UserConfig.parse(input)
+}

package/source/actions/config/define.unit.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vite-plus/test"
+import { defineConfig } from "./define.ts"
+
+describe("defineConfig", () => {
+  it("should accept include as a string", () => {
+    const config = defineConfig({ include: "articles/**/*.mdx" })
+    expect(config.include).toBe("articles/**/*.mdx")
+  })
+
+  it("should accept include as an array", () => {
+    const config = defineConfig({
+      include: ["articles/**/*.mdx", "guides/**/*.mdx"],
+    })
+    expect(config.include).toEqual(["articles/**/*.mdx", "guides/**/*.mdx"])
+  })
+
+  it("should accept optional exclude", () => {
+    const config = defineConfig({
+      include: "**/*.mdx",
+      exclude: "drafts/**",
+    })
+    expect(config.exclude).toBe("drafts/**")
+  })
+
+  it("should allow omitting exclude", () => {
+    const config = defineConfig({ include: "**/*.mdx" })
+    expect(config.exclude).toBeUndefined()
+  })
+
+  it("should reject missing include", () => {
+    expect(() => defineConfig({} as any)).toThrow()
+  })
+})

package/source/actions/config/load.ts

@@ -0,0 +1,22 @@
+import { dirname, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { z } from "zod"
+import type { Config } from "../../models/config.ts"
+import { UserConfig } from "../../models/config.ts"
+import { defineConfig } from "./define.ts"
+
+/**
+ * Load and validate a config file, checking --config/-c CLI arg, then cwd.
+ */
+export async function loadConfig(path?: string): Promise<Config> {
+  const configIndex = process.argv.findIndex(
+    a => a === "-c" || a === "--config",
+  )
+  const cliPath = configIndex !== -1 ? process.argv[configIndex + 1] : undefined
+  const resolved = resolve(path ?? cliPath ?? "livemark.config.ts")
+  // Cache-bust the ESM import so dev-server restart reloads edits on disk.
+  const url = `${pathToFileURL(resolved).href}?t=${Date.now()}`
+  const module: Record<string, unknown> = await import(url)
+  const input = defineConfig(module.default as z.input<typeof UserConfig>)
+  return { ...input, root: dirname(resolved), configPath: resolved }
+}

package/source/actions/config/load.unit.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { loadConfig } from "./load.ts"
+
+describe("loadConfig", () => {
+  it("should throw when no config file exists", async () => {
+    await expect(loadConfig("/nonexistent/config.ts")).rejects.toThrow()
+  })
+
+  it("should load config from explicit path", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const configPath = join(tmpDir, "livemark.config.ts")
+      fs.writeFileSync(
+        configPath,
+        'export default { include: "articles/**/*.mdx" }\n',
+      )
+      const config = await loadConfig(configPath)
+      expect(config.include).toBe("articles/**/*.mdx")
+      expect(config.root).toBe(tmpDir)
+    }))
+
+  it("should validate loaded config", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const configPath = join(tmpDir, "livemark.config.ts")
+      fs.writeFileSync(configPath, "export default {}\n")
+      await expect(loadConfig(configPath)).rejects.toThrow()
+    }))
+})

package/source/commands/build.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path"
+import { Command } from "commander"
+import { createBuilder } from "vite"
+
+const configFile = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "source",
+  "vite.config.ts",
+)
+
+/**
+ * Build the site for production.
+ */
+export const build = new Command("build")
+  .description("Build the site for production")
+  .action(async () => {
+    const builder = await createBuilder({ configFile })
+    await builder.buildApp()
+  })

package/source/commands/escape.ts

@@ -0,0 +1,77 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, join } from "node:path"
+import { Command } from "commander"
+import pc from "picocolors"
+import { OVERRIDE_SUBDIRS } from "../settings.ts"
+
+const defaultsRoot = join(import.meta.dirname, "..", "..", "source")
+
+/**
+ * List or copy overridable livemark files into `.livemark/`.
+ *
+ * Without an argument, prints every file you can shadow. With a path, copies
+ * the default from the livemark package into `.livemark/<path>`; fails if the
+ * destination already exists.
+ */
+export const escape = new Command("escape")
+  .description("List or copy overridable livemark files into .livemark/")
+  .argument(
+    "[path]",
+    "path relative to .livemark/ (e.g. components/Footer.tsx)",
+  )
+  .action((relPath?: string) => {
+    if (!relPath) {
+      for (const file of listOverridable()) console.log(file)
+      console.log(
+        pc.dim("\nRun 'livemark escape <path>' to copy a file into .livemark/"),
+      )
+      return
+    }
+
+    const [first] = relPath.split("/")
+    if (!first || !OVERRIDE_SUBDIRS.includes(first) || relPath.includes("..")) {
+      console.error(
+        pc.red(
+          `Error: '${relPath}' is not under an overridable subdir (${OVERRIDE_SUBDIRS.join(", ")})`,
+        ),
+      )
+      process.exit(1)
+    }
+
+    const src = join(defaultsRoot, relPath)
+    if (!existsSync(src) || !statSync(src).isFile()) {
+      console.error(pc.red(`Error: '${relPath}' is not a livemark file`))
+      process.exit(1)
+    }
+
+    const dest = join(process.cwd(), ".livemark", relPath)
+    if (existsSync(dest)) {
+      console.error(pc.red(`Error: .livemark/${relPath} already exists`))
+      process.exit(1)
+    }
+
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, readFileSync(src))
+    console.log(
+      `Copied ${pc.dim(relPath)} → ${pc.green(`.livemark/${relPath}`)}`,
+    )
+  })
+
+function listOverridable() {
+  const files: string[] = []
+  for (const subdir of OVERRIDE_SUBDIRS) {
+    const dir = join(defaultsRoot, subdir)
+    if (!existsSync(dir)) continue
+    for (const entry of readdirSync(dir)) {
+      if (statSync(join(dir, entry)).isFile()) files.push(`${subdir}/${entry}`)
+    }
+  }
+  return files.sort()
+}

package/source/commands/preview.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path"
+import { Command } from "commander"
+import { preview as vitePreview } from "vite"
+
+const configFile = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "source",
+  "vite.config.ts",
+)
+
+/**
+ * Preview the production build locally.
+ */
+export const preview = new Command("preview")
+  .description("Preview the production build locally")
+  .action(async () => {
+    const server = await vitePreview({
+      configFile,
+      preview: { port: 8000, host: true },
+    })
+    server.printUrls()
+    server.bindCLIShortcuts({ print: true })
+  })

package/source/commands/start.ts

@@ -0,0 +1,26 @@
+import { join } from "node:path"
+import { Command } from "commander"
+import { createServer } from "vite"
+
+const configFile = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "source",
+  "vite.config.ts",
+)
+
+/**
+ * Start a development server.
+ */
+export const start = new Command("start")
+  .description("Start a live server")
+  .action(async () => {
+    const server = await createServer({
+      configFile,
+      server: { port: 8000, host: true },
+    })
+    await server.listen()
+    server.printUrls()
+    server.bindCLIShortcuts({ print: true })
+  })

package/{build/website → source}/components/Article.tsx

@@ -102,7 +102,12 @@ export function Article(props: { article: ArticleView }) {
     <TocContext.Provider value={article.tocItems}>
       {article.toc !== false && (
         <MobileToc items={article.tocItems}>
-          <PageToolbar file={article.file} content={article.content} />
+          <PageToolbar
+            file={article.file}
+            sourceUrl={article.sourceUrl}
+            sourceAction={article.sourceAction}
+            content={article.content}
+          />
         </MobileToc>
       )}
       <div className="flex flex-1 gap-10 p-4 pt-8 md:p-10">
@@ -154,7 +159,12 @@ export function Article(props: { article: ArticleView }) {
         </div>
         {article.toc !== false && (
           <Toc items={article.tocItems}>
-            <PageToolbar file={article.file} content={article.content} />
+            <PageToolbar
+              file={article.file}
+              sourceUrl={article.sourceUrl}
+              sourceAction={article.sourceAction}
+              content={article.content}
+            />
           </Toc>
         )}
       </div>

package/{build/website → source}/components/Callout.tsx

@@ -1,5 +1,5 @@
 import { AlertTriangle, Flame, Info, Lightbulb } from "lucide-react"
-import { cn } from "../helpers/style.ts"
+import { cn } from "../utils/style.ts"
 
 type CalloutType = "note" | "tip" | "info" | "warning" | "danger"