devvami 1.0.0 → 1.1.0

package/src/services/awesome-copilot.js

@@ -0,0 +1,123 @@
+import { createOctokit } from './github.js'
+import { DvmiError } from '../utils/errors.js'
+
+/** @import { AwesomeEntry } from '../types.js' */
+
+/**
+ * Supported categories in github/awesome-copilot.
+ * Each maps to `docs/README.<category>.md` in the repository.
+ * @type {string[]}
+ */
+export const AWESOME_CATEGORIES = ['agents', 'instructions', 'skills', 'plugins', 'hooks', 'workflows']
+
+const AWESOME_REPO = { owner: 'github', repo: 'awesome-copilot' }
+
+/**
+ * Parse a GitHub-flavoured markdown table into AwesomeEntry objects.
+ *
+ * Expects at least two columns: `| Name/Link | Description |`
+ * The first column may contain `[text](url)` markdown links; badge images
+ * (e.g. `[![foo](img)](url)`) are stripped so only the text survives.
+ *
+ * @param {string} md - Raw markdown content of the file
+ * @param {string} category - Category label attached to every returned entry
+ * @returns {AwesomeEntry[]}
+ */
+export function parseMarkdownTable(md, category) {
+  /** @type {AwesomeEntry[]} */
+  const entries = []
+
+  for (const line of md.split('\n')) {
+    // Only process table data rows (start + end with |, not separator rows)
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) continue
+    if (/^\|[\s\-:|]+\|/.test(trimmed)) continue // header separator
+
+    const cells = trimmed
+      .slice(1, -1) // remove leading and trailing |
+      .split('|')
+      .map((c) => c.trim())
+
+    if (cells.length < 2) continue
+
+    const rawName = cells[0]
+    const description = cells[1] ?? ''
+
+    // Skip header row (first column is literally "Name" or similar)
+    if (/^[\*_]?name[\*_]?$/i.test(rawName)) continue
+
+    // Strip badge images: [![alt](img)](url) → keep nothing; [![alt](img)] → keep nothing
+    const noBadge = rawName.replace(/\[!\[.*?\]\(.*?\)\]\(.*?\)/g, '').replace(/!\[.*?\]\(.*?\)/g, '').trim()
+
+    // Extract [text](url) link
+    const linkMatch = noBadge.match(/\[([^\]]+)\]\(([^)]+)\)/)
+    const name = linkMatch ? linkMatch[1].trim() : noBadge.replace(/\[|\]/g, '').trim()
+    const url = linkMatch ? linkMatch[2].trim() : ''
+
+    if (!name) continue
+
+    entries.push(
+      /** @type {AwesomeEntry} */ ({
+        name,
+        description: description.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').trim(),
+        url,
+        category,
+        source: 'awesome-copilot',
+      }),
+    )
+  }
+
+  return entries
+}
+
+/**
+ * Fetch awesome-copilot entries for a given category from GitHub.
+ *
+ * Retrieves `docs/README.<category>.md` from the `github/awesome-copilot`
+ * repository and parses the markdown table into AwesomeEntry objects.
+ *
+ * @param {string} category - One of {@link AWESOME_CATEGORIES}
+ * @returns {Promise<AwesomeEntry[]>}
+ * @throws {DvmiError} when category is invalid, file not found, or auth is missing
+ */
+export async function fetchAwesomeEntries(category) {
+  if (!AWESOME_CATEGORIES.includes(category)) {
+    throw new DvmiError(
+      `Unknown awesome-copilot category: "${category}"`,
+      `Valid categories: ${AWESOME_CATEGORIES.join(', ')}`,
+    )
+  }
+
+  const octokit = await createOctokit()
+  const path = `docs/README.${category}.md`
+
+  let data
+  try {
+    const res = await octokit.rest.repos.getContent({
+      owner: AWESOME_REPO.owner,
+      repo: AWESOME_REPO.repo,
+      path,
+    })
+    data = res.data
+  } catch (err) {
+    const status = /** @type {{ status?: number }} */ (err).status
+    if (status === 404) {
+      throw new DvmiError(
+        `Category file not found: ${path}`,
+        `Check available categories: ${AWESOME_CATEGORIES.join(', ')}`,
+      )
+    }
+    throw err
+  }
+
+  const file = /** @type {{ content?: string, encoding?: string }} */ (data)
+  if (!file.content || file.encoding !== 'base64') {
+    throw new DvmiError(
+      `Unable to read awesome-copilot category: ${category}`,
+      'The file may be a directory or have an unsupported encoding',
+    )
+  }
+
+  const md = Buffer.from(file.content.replace(/\n/g, ''), 'base64').toString('utf8')
+  return parseMarkdownTable(md, category)
+}

package/src/services/github.js

@@ -20,7 +20,8 @@ async function getToken() {
  */
 export async function createOctokit() {
   const token = await getToken()
-  return new Octokit({ auth: token })
+  const baseUrl = process.env.GITHUB_API_URL ?? 'https://api.github.com'
+  return new Octokit({ auth: token, baseUrl })
 }
 
 /**

package/src/services/prompts.js

@@ -0,0 +1,307 @@
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { execa } from 'execa'
+import { createOctokit } from './github.js'
+import { which } from './shell.js'
+import { parseFrontmatter, serializeFrontmatter } from '../utils/frontmatter.js'
+import { DvmiError } from '../utils/errors.js'
+
+/** @import { Prompt, AITool } from '../types.js' */
+
+/**
+ * Supported AI tools and their invocation configuration.
+ * @type {Record<AITool, { bin: string[], promptFlag: string }>}
+ */
+export const SUPPORTED_TOOLS = {
+  opencode: { bin: ['opencode'], promptFlag: '--prompt' },
+  copilot: { bin: ['gh', 'copilot'], promptFlag: '-p' },
+}
+
+/**
+ * GitHub repository containing the personal prompt collection.
+ * @type {{ owner: string, repo: string }}
+ */
+export const PROMPT_REPO = { owner: 'savez', repo: 'prompt-for-ai' }
+
+/**
+ * Default branch used when fetching the repository tree.
+ * @type {string}
+ */
+const DEFAULT_BRANCH = 'HEAD'
+
+/**
+ * Known GitHub repository meta-files that should never appear as prompts.
+ * Matched case-insensitively against the final path component.
+ * @type {Set<string>}
+ */
+const EXCLUDED_FILENAMES = new Set([
+  'readme.md',
+  'contributing.md',
+  'pull_request_template.md',
+  'changelog.md',
+  'license.md',
+  'code_of_conduct.md',
+  'security.md',
+])
+
+/**
+ * Derive a human-readable title from a file path when no frontmatter title exists.
+ * @param {string} filePath - Relative path, e.g. "coding/refactor-prompt.md"
+ * @returns {string}
+ */
+function titleFromPath(filePath) {
+  const filename = filePath.split('/').pop() ?? filePath
+  return filename
+    .replace(/\.md$/i, '')
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/**
+ * Derive the category (top-level directory) from a file path.
+ * @param {string} filePath
+ * @returns {string|undefined}
+ */
+function categoryFromPath(filePath) {
+  const parts = filePath.split('/')
+  return parts.length > 1 ? parts[0] : undefined
+}
+
+/**
+ * Map raw GitHub file content (base64-encoded) to a Prompt object.
+ * @param {string} path - Relative path in the repo
+ * @param {string} base64Content - Base64-encoded file content from GitHub API
+ * @returns {Prompt}
+ */
+function contentToPrompt(path, base64Content) {
+  const raw = Buffer.from(base64Content, 'base64').toString('utf8')
+  const { frontmatter, body } = parseFrontmatter(raw)
+  return {
+    path,
+    title: typeof frontmatter.title === 'string' ? frontmatter.title : titleFromPath(path),
+    category: typeof frontmatter.category === 'string' ? frontmatter.category : categoryFromPath(path),
+    description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
+    tags: Array.isArray(frontmatter.tags) ? /** @type {string[]} */ (frontmatter.tags) : [],
+    body,
+    author: typeof frontmatter.author === 'string' ? frontmatter.author : undefined,
+    version: typeof frontmatter.version === 'string' ? String(frontmatter.version) : undefined,
+  }
+}
+
+/**
+ * List all prompts from the personal prompt repository.
+ *
+ * Fetches the full git tree (recursive) to find all `.md` files,
+ * then fetches each file's content to parse frontmatter.
+ *
+ * @returns {Promise<Prompt[]>}
+ * @throws {DvmiError} when GitHub authentication is missing or the repo is not found
+ */
+export async function listPrompts() {
+  const octokit = await createOctokit()
+  let tree
+  try {
+    const { data } = await octokit.rest.git.getTree({
+      owner: PROMPT_REPO.owner,
+      repo: PROMPT_REPO.repo,
+      tree_sha: DEFAULT_BRANCH,
+      recursive: '1',
+    })
+    tree = data.tree
+  } catch (err) {
+    const status = /** @type {{ status?: number }} */ (err).status
+    if (status === 404) {
+      throw new DvmiError(
+        `Repository ${PROMPT_REPO.owner}/${PROMPT_REPO.repo} not found`,
+        'Ensure the repository exists and you have access to it',
+      )
+    }
+    throw err
+  }
+
+  const mdFiles = tree.filter(
+    (item) =>
+      item.type === 'blob' &&
+      item.path?.endsWith('.md') &&
+      !EXCLUDED_FILENAMES.has(item.path.split('/').pop()?.toLowerCase() ?? ''),
+  )
+
+  if (mdFiles.length === 0) {
+    return []
+  }
+
+  const prompts = await Promise.all(
+    mdFiles.map(async (item) => {
+      const { data } = await octokit.rest.repos.getContent({
+        owner: PROMPT_REPO.owner,
+        repo: PROMPT_REPO.repo,
+        path: item.path ?? '',
+      })
+      // getContent returns a single file object when path is a file
+      const file = /** @type {{ content?: string, encoding?: string }} */ (data)
+      if (!file.content || file.encoding !== 'base64') {
+        return null
+      }
+      return contentToPrompt(item.path ?? '', file.content.replace(/\n/g, ''))
+    }),
+  )
+
+  return /** @type {Prompt[]} */ (prompts.filter(Boolean))
+}
+
+/**
+ * Fetch a single prompt by its relative path in the repository.
+ *
+ * @param {string} relativePath - Path relative to repo root (e.g. "coding/refactor-prompt.md")
+ * @returns {Promise<Prompt>}
+ * @throws {DvmiError} when the file is not found or authentication is missing
+ */
+export async function fetchPromptByPath(relativePath) {
+  const octokit = await createOctokit()
+  let data
+  try {
+    const res = await octokit.rest.repos.getContent({
+      owner: PROMPT_REPO.owner,
+      repo: PROMPT_REPO.repo,
+      path: relativePath,
+    })
+    data = res.data
+  } catch (err) {
+    const status = /** @type {{ status?: number }} */ (err).status
+    if (status === 404) {
+      throw new DvmiError(
+        `Prompt not found: ${relativePath}`,
+        `Run \`dvmi prompts list\` to see available prompts`,
+      )
+    }
+    throw err
+  }
+
+  const file = /** @type {{ content?: string, encoding?: string }} */ (data)
+  if (!file.content || file.encoding !== 'base64') {
+    throw new DvmiError(
+      `Unable to read prompt: ${relativePath}`,
+      'The file may be a directory or have an unsupported encoding',
+    )
+  }
+
+  return contentToPrompt(relativePath, file.content.replace(/\n/g, ''))
+}
+
+/**
+ * Download a prompt from the repository to a local directory.
+ *
+ * If the destination file already exists and `opts.overwrite` is not `true`,
+ * the function returns immediately with `{ skipped: true }` without making
+ * any network request.
+ *
+ * @param {string} relativePath - Path relative to repo root (e.g. "coding/refactor-prompt.md")
+ * @param {string} localDir - Local base directory (e.g. "/project/.prompts")
+ * @param {{ overwrite?: boolean }} [opts]
+ * @returns {Promise<{ path: string, skipped: boolean }>}
+ * @throws {DvmiError} when the prompt is not found or the write fails
+ */
+export async function downloadPrompt(relativePath, localDir, opts = {}) {
+  const destPath = join(localDir, relativePath)
+
+  // Fast-path: skip without a network round-trip if file exists and no overwrite
+  if (!opts.overwrite) {
+    try {
+      await access(destPath)
+      return { path: destPath, skipped: true }
+    } catch {
+      // File does not exist — fall through to download
+    }
+  }
+
+  const prompt = await fetchPromptByPath(relativePath)
+
+  // Re-build frontmatter from the known Prompt fields
+  /** @type {Record<string, unknown>} */
+  const fm = {}
+  if (prompt.title) fm.title = prompt.title
+  if (prompt.category) fm.category = prompt.category
+  if (prompt.description) fm.description = prompt.description
+  if (prompt.tags?.length) fm.tags = prompt.tags
+  if (prompt.author) fm.author = prompt.author
+  if (prompt.version) fm.version = prompt.version
+
+  const content = serializeFrontmatter(fm, prompt.body)
+
+  await mkdir(dirname(destPath), { recursive: true })
+  await writeFile(destPath, content, 'utf8')
+
+  return { path: destPath, skipped: false }
+}
+
+/**
+ * Read and parse a prompt from the local prompt store.
+ *
+ * @param {string} relativePath - Prompt path relative to the local store root
+ *   (e.g. "coding/refactor-prompt.md")
+ * @param {string} localDir - Absolute path to the local prompts directory
+ * @returns {Promise<import('../types.js').Prompt>}
+ * @throws {DvmiError} when the file does not exist or cannot be parsed
+ */
+export async function resolveLocalPrompt(relativePath, localDir) {
+  const fullPath = join(localDir, relativePath)
+  let raw
+  try {
+    raw = await readFile(fullPath, 'utf8')
+  } catch {
+    throw new DvmiError(
+      `Local prompt not found: ${relativePath}`,
+      `Run \`dvmi prompts download ${relativePath}\` to download it first`,
+    )
+  }
+
+  const { frontmatter, body } = parseFrontmatter(raw)
+  return {
+    path: relativePath,
+    title: typeof frontmatter.title === 'string' ? frontmatter.title : titleFromPath(relativePath),
+    category: typeof frontmatter.category === 'string' ? frontmatter.category : categoryFromPath(relativePath),
+    description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
+    tags: Array.isArray(frontmatter.tags) ? /** @type {string[]} */ (frontmatter.tags) : [],
+    body,
+    author: typeof frontmatter.author === 'string' ? frontmatter.author : undefined,
+    version: typeof frontmatter.version === 'string' ? String(frontmatter.version) : undefined,
+  }
+}
+
+/**
+ * Invoke a supported AI tool with the given prompt content.
+ *
+ * Verifies the tool binary is available in PATH before spawning.
+ * Spawns with `stdio: 'inherit'` so the tool's UI is displayed directly.
+ *
+ * @param {AITool} toolName - Tool key from {@link SUPPORTED_TOOLS}
+ * @param {string} promptContent - The full prompt text to pass to the tool
+ * @returns {Promise<void>}
+ * @throws {DvmiError} when the tool is unknown or the binary is not in PATH
+ */
+export async function invokeTool(toolName, promptContent) {
+  const tool = SUPPORTED_TOOLS[toolName]
+  if (!tool) {
+    throw new DvmiError(
+      `Unknown AI tool: "${toolName}"`,
+      `Supported tools: ${Object.keys(SUPPORTED_TOOLS).join(', ')}`,
+    )
+  }
+
+  // Verify binary availability
+  const [bin, ...subArgs] = tool.bin
+  const binPath = await which(bin)
+  if (!binPath) {
+    const installHints = {
+      opencode: 'Install opencode: npm install -g opencode',
+      copilot: 'Install GitHub CLI: https://cli.github.com',
+    }
+    throw new DvmiError(
+      `${bin} is not installed or not in PATH`,
+      installHints[toolName] ?? `Install ${bin} and ensure it is in your PATH`,
+    )
+  }
+
+  // Spawn tool with prompt content — inherits stdio so TUI/interactive tools work
+  await execa(bin, [...subArgs, tool.promptFlag, promptContent], { stdio: 'inherit' })
+}

package/src/services/skills-sh.js

@@ -0,0 +1,81 @@
+import { DvmiError } from '../utils/errors.js'
+
+/** @import { Skill } from '../types.js' */
+
+const SKILLS_SH_DEFAULT = 'https://skills.sh'
+
+/**
+ * Base URL for the skills.sh API.
+ * Overridable via SKILLS_SH_BASE_URL env var (used in tests).
+ * @returns {string}
+ */
+function skillsBaseUrl() {
+  return process.env.SKILLS_SH_BASE_URL ?? SKILLS_SH_DEFAULT
+}
+
+/**
+ * Search for skills on skills.sh.
+ *
+ * @param {string} query - Search query string (must be at least 2 characters)
+ * @param {number} [limit=50] - Maximum number of results
+ * @returns {Promise<Skill[]>}
+ * @throws {DvmiError} when query is too short, the API is unreachable or returns an unexpected response
+ */
+export async function searchSkills(query, limit = 50) {
+  if (!query || query.length < 2) {
+    throw new DvmiError(
+      'skills.sh requires a search query of at least 2 characters',
+      'Use --query to search, e.g. dvmi prompts browse skills --query refactor',
+    )
+  }
+
+  const url = new URL('/api/search', skillsBaseUrl())
+  url.searchParams.set('q', query)
+  url.searchParams.set('limit', String(limit))
+
+  let res
+  try {
+    res = await fetch(url.toString())
+  } catch {
+    throw new DvmiError(
+      'Unable to reach skills.sh API',
+      'Check your internet connection and try again',
+    )
+  }
+
+  if (!res.ok) {
+    throw new DvmiError(
+      `skills.sh API returned ${res.status}`,
+      'Try again later or visit https://skills.sh',
+    )
+  }
+
+  /** @type {unknown} */
+  let json
+  try {
+    json = await res.json()
+  } catch {
+    throw new DvmiError('Unexpected response from skills.sh', 'Try again later')
+  }
+
+  // skills.sh returns { skills: [...], count, ... } — also handle legacy { results: [...] } or plain array
+  const items = Array.isArray(json)
+    ? json
+    : Array.isArray(/** @type {Record<string,unknown>} */ (json)?.skills)
+      ? /** @type {Record<string,unknown>[]} */ (/** @type {Record<string,unknown>} */ (json).skills)
+      : Array.isArray(/** @type {Record<string,unknown>} */ (json)?.results)
+        ? /** @type {Record<string,unknown>[]} */ (/** @type {Record<string,unknown>} */ (json).results)
+        : []
+
+  return items.map((item) => {
+    const s = /** @type {Record<string, unknown>} */ (item)
+    return /** @type {Skill} */ ({
+      id: String(s.id ?? s.slug ?? ''),
+      name: String(s.name ?? s.title ?? ''),
+      description: typeof s.description === 'string' ? s.description : undefined,
+      installs: typeof s.installs === 'number' ? s.installs : undefined,
+      url: typeof s.url === 'string' ? s.url : `https://skills.sh/skills/${s.id ?? s.slug ?? ''}`,
+      source: 'skills.sh',
+    })
+  })
+}

package/src/services/speckit.js

@@ -0,0 +1,73 @@
+import { execa } from 'execa'
+import { which, exec } from './shell.js'
+import { DvmiError } from '../utils/errors.js'
+
+/** GitHub spec-kit package source for uv */
+const SPECKIT_FROM = 'git+https://github.com/github/spec-kit.git'
+
+/**
+ * Check whether the `uv` Python package manager is available in PATH.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function isUvInstalled() {
+  return (await which('uv')) !== null
+}
+
+/**
+ * Check whether the `specify` CLI (spec-kit) is available in PATH.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function isSpecifyInstalled() {
+  return (await which('specify')) !== null
+}
+
+/**
+ * Install `specify-cli` from the GitHub spec-kit repository via `uv tool install`.
+ *
+ * @param {{ force?: boolean }} [opts] - Pass `force: true` to reinstall even if already present
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>}
+ * @throws {DvmiError} when the installation command fails
+ */
+export async function installSpecifyCli(opts = {}) {
+  const args = ['tool', 'install', 'specify-cli', '--from', SPECKIT_FROM]
+  if (opts.force) args.push('--force')
+
+  const result = await exec('uv', args)
+  if (result.exitCode !== 0) {
+    throw new DvmiError(
+      'Failed to install specify-cli',
+      result.stderr || 'Check your network connection and uv installation, then try again',
+    )
+  }
+  return result
+}
+
+/**
+ * Run `specify init --here` in the given directory, inheriting the parent
+ * stdio so the user can interact with the speckit wizard directly.
+ *
+ * @param {string} cwd - Working directory to run `specify init` in
+ * @param {{ ai?: string, force?: boolean }} [opts]
+ * @returns {Promise<void>}
+ * @throws {DvmiError} when `specify init` exits with a non-zero code
+ */
+export async function runSpecifyInit(cwd, opts = {}) {
+  const args = ['init', '--here']
+  if (opts.ai) args.push('--ai', opts.ai)
+  if (opts.force) args.push('--force')
+
+  const result = await execa('specify', args, {
+    cwd,
+    stdio: 'inherit',
+    reject: false,
+  })
+
+  if (result.exitCode !== 0) {
+    throw new DvmiError(
+      '`specify init` exited with a non-zero code',
+      'Check the output above for details',
+    )
+  }
+}

package/src/types.js

@@ -12,6 +12,40 @@
  * @property {{ teamId?: string, teamName?: string, authMethod?: 'oauth' | 'personal_token' }} [clickup] - ClickUp workspace config
  * @property {string} [lastVersionCheck] - ISO8601 timestamp of last version check
  * @property {string} [latestVersion] - Latest known CLI version
+ * @property {'opencode'|'copilot'} [aiTool] - Preferred AI tool for running prompts
+ * @property {string} [promptsDir] - Local directory for downloaded prompts (default: .prompts)
+ */
+
+/**
+ * @typedef {Object} Prompt
+ * @property {string} path - Relative path in the repo (e.g. "coding/refactor-prompt.md")
+ * @property {string} title - Human-readable title (from frontmatter or filename)
+ * @property {string} [category] - Category derived from parent directory (e.g. "coding")
+ * @property {string} [description] - Short description from frontmatter
+ * @property {string[]} [tags] - Tags from frontmatter
+ * @property {string} body - Full prompt content (without frontmatter)
+ * @property {string} [author] - Author from frontmatter
+ * @property {string} [version] - Version string from frontmatter
+ */
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} id - Unique skill identifier on skills.sh
+ * @property {string} name - Display name
+ * @property {number} installs - Install count
+ * @property {string} source - Source URL or identifier
+ */
+
+/**
+ * @typedef {Object} AwesomeEntry
+ * @property {string} name - Entry name
+ * @property {string} description - Short description
+ * @property {string} url - Link to the resource
+ * @property {string} category - Category (agents, instructions, skills, plugins, hooks, workflows)
+ */
+
+/**
+ * @typedef {'opencode'|'copilot'} AITool
  */
 
 /**

package/src/utils/frontmatter.js

@@ -0,0 +1,52 @@
+import yaml from 'js-yaml'
+
+/**
+ * @typedef {Object} ParsedFrontmatter
+ * @property {Record<string, unknown>} frontmatter - Parsed YAML frontmatter object (empty if none)
+ * @property {string} body - Body content without frontmatter
+ */
+
+/**
+ * Parse YAML frontmatter from a markdown string.
+ *
+ * Expects optional leading `---\n...\n---\n` block.
+ * Returns an empty frontmatter object if none is found.
+ *
+ * @param {string} content - Raw file content
+ * @returns {ParsedFrontmatter}
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)---\r?\n?([\s\S]*)$/)
+  if (!match) {
+    return { frontmatter: {}, body: content }
+  }
+  const rawYaml = match[1]
+  const body = match[2] ?? ''
+  try {
+    const parsed = yaml.load(rawYaml)
+    const frontmatter =
+      parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? /** @type {Record<string, unknown>} */ (parsed)
+        : {}
+    return { frontmatter, body }
+  } catch {
+    return { frontmatter: {}, body: content }
+  }
+}
+
+/**
+ * Serialize a frontmatter object and body back into a markdown string.
+ *
+ * If `frontmatter` is empty (`{}`), returns `body` without a frontmatter block.
+ *
+ * @param {Record<string, unknown>} frontmatter - Frontmatter data to serialize
+ * @param {string} body - Body content
+ * @returns {string}
+ */
+export function serializeFrontmatter(frontmatter, body) {
+  if (!frontmatter || Object.keys(frontmatter).length === 0) {
+    return body
+  }
+  const yamlStr = yaml.dump(frontmatter, { lineWidth: -1 }).trimEnd()
+  return `---\n${yamlStr}\n---\n${body}`
+}