@lavralabs/lavra 0.7.0

package/scripts/pre-release-check.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# Pre-release checks that mirror the CI verify-release job.
+# Run this before tagging a release to catch failures locally.
+#
+# SYNC: This script must stay in sync with the `verify-release` job in
+# .github/workflows/test-installation.yml. When modifying either file,
+# update the other to match.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+PASS=0
+FAIL=0
+
+check() {
+  local label="$1"
+  shift
+  if "$@" 2>/dev/null; then
+    echo "  PASS  $label"
+    ((PASS++)) || true
+  else
+    echo "  FAIL  $label"
+    ((FAIL++)) || true
+  fi
+}
+
+fail() {
+  local label="$1"
+  local msg="$2"
+  echo "  FAIL  $label: $msg"
+  ((FAIL++)) || true
+}
+
+echo ""
+echo "=== Version consistency ==="
+
+PLUGIN_VERSION=$(jq -r '.version' plugins/lavra/.claude-plugin/plugin.json)
+MARKETPLACE_VERSION=$(jq -r '.plugins[] | select(.name == "lavra") | .version' .claude-plugin/marketplace.json)
+
+echo "  plugin.json:      $PLUGIN_VERSION"
+echo "  marketplace.json: $MARKETPLACE_VERSION"
+
+if [[ "$PLUGIN_VERSION" == "$MARKETPLACE_VERSION" ]]; then
+  echo "  PASS  Versions match"
+  ((PASS++)) || true
+else
+  fail "Version mismatch" "plugin.json=$PLUGIN_VERSION marketplace.json=$MARKETPLACE_VERSION"
+fi
+
+echo ""
+echo "=== Hook version constants ==="
+
+HOOK_VERSION=$(grep 'LAVRA_VERSION=' plugins/lavra/hooks/auto-recall.sh | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+PROVISION_VERSION=$(grep 'echo "' plugins/lavra/hooks/provision-memory.sh | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+
+echo "  auto-recall.sh:       $HOOK_VERSION"
+echo "  provision-memory.sh:  $PROVISION_VERSION"
+
+[[ "$HOOK_VERSION" == "$PLUGIN_VERSION" ]] && { echo "  PASS  auto-recall.sh version"; ((PASS++)) || true; } || fail "auto-recall.sh version" "has $HOOK_VERSION, expected $PLUGIN_VERSION"
+[[ "$PROVISION_VERSION" == "$PLUGIN_VERSION" ]] && { echo "  PASS  provision-memory.sh version"; ((PASS++)) || true; } || fail "provision-memory.sh version" "has $PROVISION_VERSION, expected $PLUGIN_VERSION"
+
+echo ""
+echo "=== Conversion outputs ==="
+echo "  Generating OpenCode and Gemini outputs..."
+(cd scripts && bun install --frozen-lockfile --silent && bun run convert-opencode.ts && bun run convert-gemini.ts && bun run convert-cortex.ts) || {
+  fail "Conversion scripts" "bun run failed"
+}
+
+echo ""
+echo "=== Component counts ==="
+
+COMMANDS=$(find plugins/lavra/commands -maxdepth 1 -name "*.md" | wc -l | tr -d ' ')
+OPTIONAL_COMMANDS=$(find plugins/lavra/commands/optional -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+AGENTS=$(find plugins/lavra/agents -name "*.md" | wc -l | tr -d ' ')
+SKILLS=$(find plugins/lavra/skills -name "SKILL.md" | wc -l | tr -d ' ')
+
+echo "  Commands: $COMMANDS (need 23+) + $OPTIONAL_COMMANDS optional"
+echo "  Agents:   $AGENTS (need 30+)"
+echo "  Skills:   $SKILLS (need 15+)"
+
+[[ "$COMMANDS" -ge 23 ]] && { echo "  PASS  Commands"; ((PASS++)) || true; } || fail "Commands" "$COMMANDS < 23"
+[[ "$AGENTS"   -ge 30 ]] && { echo "  PASS  Agents";   ((PASS++)) || true; } || fail "Agents"   "$AGENTS < 30"
+[[ "$SKILLS"   -ge 15 ]] && { echo "  PASS  Skills";   ((PASS++)) || true; } || fail "Skills"   "$SKILLS < 15"
+
+echo ""
+echo "=== Source files ==="
+
+check "opencode-src/plugin.ts"    test -f plugins/lavra/opencode-src/plugin.ts
+check "opencode-src/package.json" test -f plugins/lavra/opencode-src/package.json
+check "gemini-src/settings.json"  test -f plugins/lavra/gemini-src/settings.json
+
+echo ""
+echo "=== Conversion output files ==="
+
+check "opencode/ directory" test -d plugins/lavra/opencode
+check "gemini/ directory"   test -d plugins/lavra/gemini
+check "cortex/ directory"   test -d plugins/lavra/cortex
+
+OPENCODE_COMMANDS=$(find plugins/lavra/opencode/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+GEMINI_TOML=$(find plugins/lavra/gemini/commands -name "*.toml" 2>/dev/null | wc -l | tr -d ' ')
+
+echo "  OpenCode .md commands: $OPENCODE_COMMANDS (need 23+)"
+echo "  Gemini .toml commands: $GEMINI_TOML (need 23+)"
+
+[[ "$OPENCODE_COMMANDS" -ge 23 ]] && { echo "  PASS  OpenCode commands"; ((PASS++)) || true; } || fail "OpenCode commands" "$OPENCODE_COMMANDS < 23"
+[[ "$GEMINI_TOML"       -ge 23 ]] && { echo "  PASS  Gemini commands";   ((PASS++)) || true; } || fail "Gemini commands"   "$GEMINI_TOML < 23"
+
+CORTEX_COMMANDS=$(find plugins/lavra/cortex/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+echo "  Cortex .md commands:   $CORTEX_COMMANDS (need 20+)"
+[[ "$CORTEX_COMMANDS" -ge 20 ]] && { echo "  PASS  Cortex commands"; ((PASS++)) || true; } || fail "Cortex commands" "$CORTEX_COMMANDS < 20"
+
+echo ""
+echo "=== Command map ==="
+
+check "site/public/command-map.html exists" test -f site/public/command-map.html
+
+# Verify command map references current node counts (spot check: NODES array has entries)
+MAP_NODES=$(grep -c "id:'" site/public/command-map.html || echo 0)
+echo "  Command map nodes: $MAP_NODES (need 40+)"
+[[ "$MAP_NODES" -ge 40 ]] && { echo "  PASS  Command map nodes"; ((PASS++)) || true; } || fail "Command map nodes" "$MAP_NODES < 40"
+
+echo ""
+echo "=== Catalog accuracy ==="
+# SYNC: This section must stay in sync with the verify-docs step in .github/workflows/test-installation.yml.
+# When modifying either, update the other.
+
+# Extract command names from CATALOG.md table rows only (lines starting with |)
+# to avoid matching prose mentions like "Included in `/lavra-design`"
+CATALOG_COMMANDS=$(grep -E '^\|' site/src/content/docs/CATALOG.md | \
+  grep -oE '`/[a-z][a-z0-9-]+`' | tr -d '`' | sed 's|^/||' | sort -u)
+
+# Actual command files (core + optional, recurse into subdirs)
+ACTUAL_COMMANDS=$(find plugins/lavra/commands -name "*.md" | \
+  xargs -I{} basename {} .md 2>/dev/null | sort -u)
+
+GHOST_COUNT=0
+MISSING_COUNT=0
+
+# Check for ghost commands (in catalog, no file exists)
+while IFS= read -r cmd; do
+  if ! echo "$ACTUAL_COMMANDS" | grep -qx "$cmd"; then
+    fail "Catalog ghost" "/${cmd} listed in CATALOG.md but no ${cmd}.md file found"
+    ((GHOST_COUNT++)) || true
+  fi
+done <<< "$CATALOG_COMMANDS"
+
+# Check for missing catalog entries (file exists, not in catalog)
+while IFS= read -r cmd; do
+  if ! echo "$CATALOG_COMMANDS" | grep -qx "$cmd"; then
+    fail "Missing from catalog" "${cmd}.md exists but /${cmd} not in CATALOG.md"
+    ((MISSING_COUNT++)) || true
+  fi
+done <<< "$ACTUAL_COMMANDS"
+
+if [[ "$GHOST_COUNT" -eq 0 && "$MISSING_COUNT" -eq 0 ]]; then
+  echo "  PASS  Catalog accuracy (no ghosts, no missing entries)"
+  ((PASS++)) || true
+fi
+
+echo ""
+echo "=== Compatibility tests ==="
+(cd scripts && bun run test-compatibility.ts) && { echo "  PASS  Compatibility tests"; ((PASS++)) || true; } || fail "Compatibility tests" "see output above"
+
+echo ""
+echo "================================"
+echo "  $PASS passed, $FAIL failed"
+echo "================================"
+echo ""
+
+if [[ "$FAIL" -gt 0 ]]; then
+  echo "Fix the failures above before releasing."
+  exit 1
+fi
+
+echo "All checks passed. Safe to release."

package/scripts/select-opencode-models.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+#
+# Interactive model selection for OpenCode installation
+# Queries available models via 'opencode models' and lets user select preferences
+#
+# Usage:
+#   ./select-opencode-models.sh [--yes]
+#
+# With --yes: Uses defaults without prompting
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_FILE="$SCRIPT_DIR/shared/model-config.json"
+
+# Parse --yes flag
+AUTO_YES=false
+for arg in "$@"; do
+  case "$arg" in
+    --yes|-y) AUTO_YES=true ;;
+  esac
+done
+
+# Check if opencode is available
+if ! command -v opencode &>/dev/null; then
+  echo "[!] Error: 'opencode' command not found"
+  echo "    OpenCode must be installed to query available models"
+  echo "    Visit: https://github.com/smallcloudai/refact"
+  exit 1
+fi
+
+# Query available models
+echo "🔍 Querying available models from OpenCode..."
+MODELS_OUTPUT=$(opencode models 2>&1 || true)
+
+# Extract Anthropic/Claude models
+CLAUDE_MODELS=$(echo "$MODELS_OUTPUT" | grep -E "anthropic/claude-" | awk '{print $1}' | sort -u || true)
+
+if [ -z "$CLAUDE_MODELS" ]; then
+  echo "[!] Warning: No Anthropic/Claude models found in OpenCode"
+  echo "    Using defaults from model-config.json"
+  exit 0
+fi
+
+echo ""
+echo "Found $(echo "$CLAUDE_MODELS" | wc -l | tr -d ' ') Claude models:"
+echo "$CLAUDE_MODELS" | sed 's/^/  - /'
+echo ""
+
+# Load current config
+if [ -f "$CONFIG_FILE" ]; then
+  CURRENT_HAIKU=$(jq -r '.opencode.haiku' "$CONFIG_FILE")
+  CURRENT_SONNET=$(jq -r '.opencode.sonnet' "$CONFIG_FILE")
+  CURRENT_OPUS=$(jq -r '.opencode.opus' "$CONFIG_FILE")
+else
+  CURRENT_HAIKU="anthropic/claude-haiku-4-5-20251001"
+  CURRENT_SONNET="anthropic/claude-sonnet-4-5-20250929"
+  CURRENT_OPUS="anthropic/claude-opus-4-6"
+fi
+
+# If --yes flag, use current config
+if [ "$AUTO_YES" = true ]; then
+  echo "Using defaults (--yes flag):"
+  echo "  haiku:  $CURRENT_HAIKU"
+  echo "  sonnet: $CURRENT_SONNET"
+  echo "  opus:   $CURRENT_OPUS"
+  exit 0
+fi
+
+# Interactive selection function
+select_model() {
+  local tier="$1"
+  local current="$2"
+  local pattern="$3"
+
+  echo "Select model for $tier tier (current: $current):"
+  echo ""
+
+  # Filter models by pattern
+  local filtered=$(echo "$CLAUDE_MODELS" | grep -i "$pattern" || echo "$CLAUDE_MODELS")
+
+  # Create numbered list
+  local i=1
+  local model_array=()
+  while IFS= read -r model; do
+    model_array+=("$model")
+    if [ "$model" = "$current" ]; then
+      echo "  $i) $model (current)"
+    else
+      echo "  $i) $model"
+    fi
+    ((i++))
+  done <<< "$filtered"
+
+  echo "  0) Keep current ($current)"
+  echo ""
+
+  # Get user selection
+  while true; do
+    read -p "Selection (0-$((i-1))): " selection
+
+    if [[ "$selection" =~ ^[0-9]+$ ]]; then
+      if [ "$selection" -eq 0 ]; then
+        echo "$current"
+        return
+      elif [ "$selection" -ge 1 ] && [ "$selection" -lt "$i" ]; then
+        echo "${model_array[$((selection-1))]}"
+        return
+      fi
+    fi
+
+    echo "Invalid selection. Please enter a number between 0 and $((i-1))."
+  done
+}
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Model Selection"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Select models for each tier
+HAIKU_MODEL=$(select_model "haiku" "$CURRENT_HAIKU" "haiku")
+echo ""
+
+SONNET_MODEL=$(select_model "sonnet" "$CURRENT_SONNET" "sonnet")
+echo ""
+
+OPUS_MODEL=$(select_model "opus" "$CURRENT_OPUS" "opus")
+echo ""
+
+# Confirm selections
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Selected Models:"
+echo "  haiku:  $HAIKU_MODEL"
+echo "  sonnet: $SONNET_MODEL"
+echo "  opus:   $OPUS_MODEL"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+read -p "Save this configuration? (y/N): " confirm
+if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+  echo "Configuration not saved."
+  exit 0
+fi
+
+# Create config directory if needed
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+# Load existing config or create new
+if [ -f "$CONFIG_FILE" ]; then
+  CONFIG=$(cat "$CONFIG_FILE")
+else
+  CONFIG='{}'
+fi
+
+# Update OpenCode models
+CONFIG=$(echo "$CONFIG" | jq ".opencode.haiku = \"$HAIKU_MODEL\"")
+CONFIG=$(echo "$CONFIG" | jq ".opencode.sonnet = \"$SONNET_MODEL\"")
+CONFIG=$(echo "$CONFIG" | jq ".opencode.opus = \"$OPUS_MODEL\"")
+
+# Ensure Gemini config exists (preserve existing if present)
+if ! echo "$CONFIG" | jq -e '.gemini' >/dev/null 2>&1; then
+  CONFIG=$(echo "$CONFIG" | jq '.gemini = {
+    "haiku": "gemini-2.5-flash",
+    "sonnet": "gemini-2.5-pro",
+    "opus": "gemini-2.5-pro"
+  }')
+fi
+
+# Write config file
+echo "$CONFIG" | jq . > "$CONFIG_FILE"
+
+echo ""
+echo "✅ Configuration saved to: $CONFIG_FILE"
+echo ""
+echo "Next steps:"
+echo "  Run the OpenCode installer to use these model selections"

package/scripts/shared/model-config.json

@@ -0,0 +1,17 @@
+{
+  "opencode": {
+    "haiku": "anthropic/claude-haiku-4-5-20251001",
+    "sonnet": "anthropic/claude-sonnet-4-5-20250929",
+    "opus": "anthropic/claude-opus-4-6"
+  },
+  "gemini": {
+    "haiku": "gemini-2.5-flash",
+    "sonnet": "gemini-2.5-pro",
+    "opus": "gemini-2.5-pro"
+  },
+  "cortex": {
+    "haiku": "haiku",
+    "sonnet": "sonnet",
+    "opus": "opus"
+  }
+}

package/scripts/shared/model-mapping.ts

@@ -0,0 +1,129 @@
+/**
+ * Model tier mapping across platforms
+ * Preserves cost/quality tiers (haiku/sonnet/opus) while using platform-native models
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Load model configuration from file
+let modelConfig: any;
+try {
+  const configPath = join(import.meta.dir, "model-config.json");
+  modelConfig = JSON.parse(readFileSync(configPath, "utf-8"));
+} catch {
+  // Fallback to defaults if config file doesn't exist
+  modelConfig = {
+    opencode: {
+      haiku: "anthropic/claude-haiku-4-5-20251001",
+      sonnet: "anthropic/claude-sonnet-4-5-20250929",
+      opus: "anthropic/claude-opus-4-6",
+    },
+    gemini: {
+      haiku: "gemini-2.5-flash",
+      sonnet: "gemini-2.5-pro",
+      opus: "gemini-2.5-pro",
+    },
+    cortex: {
+      haiku: "haiku",
+      sonnet: "sonnet",
+      opus: "opus",
+    },
+  };
+}
+
+export const MODEL_TIERS = {
+  claude: {
+    haiku: "haiku",
+    sonnet: "sonnet",
+    opus: "opus",
+    inherit: "inherit",
+  },
+  opencode: {
+    haiku: modelConfig.opencode.haiku,
+    sonnet: modelConfig.opencode.sonnet,
+    opus: modelConfig.opencode.opus,
+    inherit: "inherit",
+  },
+  gemini: {
+    haiku: modelConfig.gemini.haiku,
+    sonnet: modelConfig.gemini.sonnet,
+    opus: modelConfig.gemini.opus, // Gemini has no equivalent to Opus, use Pro
+    inherit: "inherit",
+  },
+  cortex: {
+    haiku: modelConfig.cortex?.haiku ?? "haiku",
+    sonnet: modelConfig.cortex?.sonnet ?? "sonnet",
+    opus: modelConfig.cortex?.opus ?? "opus",
+    inherit: "inherit",
+  },
+} as const;
+
+/**
+ * Maps a Claude Code model tier to OpenCode model ID
+ */
+export function mapToOpenCode(claudeModel: string): string {
+  const model = claudeModel.toLowerCase();
+
+  // If already a full model ID, validate and return
+  if (model.includes("/") || model.includes("-")) {
+    return claudeModel;
+  }
+
+  // Map tier to OpenCode model ID
+  const tier = model as keyof typeof MODEL_TIERS.opencode;
+  if (tier in MODEL_TIERS.opencode) {
+    return MODEL_TIERS.opencode[tier];
+  }
+
+  // Default to inherit if unknown
+  return "inherit";
+}
+
+/**
+ * Maps a Claude Code model tier to Gemini model ID
+ */
+export function mapToGemini(claudeModel: string): string {
+  const model = claudeModel.toLowerCase();
+
+  // If it's "inherit", keep it
+  if (model === "inherit") {
+    return "inherit";
+  }
+
+  // If already a Gemini model, return as-is
+  if (model.startsWith("gemini-")) {
+    return claudeModel;
+  }
+
+  // Map tier to Gemini model ID
+  const tier = model as keyof typeof MODEL_TIERS.gemini;
+  if (tier in MODEL_TIERS.gemini) {
+    return MODEL_TIERS.gemini[tier];
+  }
+
+  // Default to gemini-2.5-pro if unknown
+  return "gemini-2.5-pro";
+}
+
+/**
+ * Maps a Claude Code model tier to Cortex Code model tier
+ * Identity mapping: Cortex uses the same tier names as Claude
+ */
+export function mapToCortex(claudeModel: string): string {
+  const model = claudeModel.toLowerCase();
+
+  // If it's "inherit", keep it
+  if (model === "inherit") {
+    return "inherit";
+  }
+
+  // Map tier to Cortex model tier (identity mapping)
+  const tier = model as keyof typeof MODEL_TIERS.cortex;
+  if (tier in MODEL_TIERS.cortex) {
+    return MODEL_TIERS.cortex[tier];
+  }
+
+  // Default to sonnet if unknown
+  return "sonnet";
+}

package/scripts/shared/security.ts

@@ -0,0 +1,97 @@
+import { resolve, relative } from "node:path";
+import { stat, chmod } from "node:fs/promises";
+
+/**
+ * Security configuration constants
+ */
+export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+export const ALLOWED_FILE_PATTERN = /^[a-zA-Z0-9._-]+\.md$/;
+export const ALLOWED_MODEL_NAMES = new Set([
+  "sonnet",
+  "opus",
+  "haiku",
+  "inherit",
+  "anthropic/claude-sonnet-4-20250514",
+  "anthropic/claude-sonnet-4-5-20250929",
+  "anthropic/claude-opus-4-6",
+  "anthropic/claude-haiku-4-5-20251001",
+  "gemini-2.5-pro",
+  "gemini-2.5-flash",
+  "gemini-2.0-flash",
+]);
+
+/**
+ * Validates that a path does not escape the base directory
+ * Prevents path traversal attacks like ../../../etc/passwd
+ */
+export function validatePath(basePath: string, targetPath: string): string {
+  const resolved = resolve(basePath, targetPath);
+  const rel = relative(basePath, resolved);
+
+  if (rel.startsWith("..") || resolve(basePath, rel) !== resolved) {
+    throw new Error(`Path traversal detected: ${targetPath}`);
+  }
+
+  return resolved;
+}
+
+/**
+ * Sanitizes a filename to prevent malicious characters
+ * Allows only alphanumeric, dots, underscores, and hyphens
+ */
+export function sanitizeFilename(filename: string): string {
+  return filename.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+/**
+ * Reads a file safely with size limit enforcement
+ */
+export async function readFileSafe(path: string): Promise<string> {
+  const stats = await stat(path);
+
+  if (stats.size > MAX_FILE_SIZE) {
+    throw new Error(
+      `File too large: ${path} (${stats.size} bytes, max ${MAX_FILE_SIZE})`
+    );
+  }
+
+  const file = Bun.file(path);
+  return await file.text();
+}
+
+/**
+ * Writes a file with explicit permissions
+ * Ensures files are not world-writable
+ */
+export async function writeFileSafe(
+  path: string,
+  content: string,
+  mode: number = 0o644
+): Promise<void> {
+  await Bun.write(path, content);
+  await chmod(path, mode);
+}
+
+/**
+ * Validates a model name against allowlist
+ * Prevents injection via model field
+ */
+export function validateModelName(modelName: string): string {
+  // Strict alphanumeric + hyphen + slash + dot validation
+  if (!/^[a-z0-9/.-]+$/i.test(modelName)) {
+    throw new Error(`Invalid model name format: ${modelName}`);
+  }
+
+  if (!ALLOWED_MODEL_NAMES.has(modelName)) {
+    throw new Error(`Unsupported model: ${modelName}`);
+  }
+
+  return modelName;
+}
+
+/**
+ * Validates a filename matches allowed pattern
+ */
+export function validateFilename(filename: string): boolean {
+  return ALLOWED_FILE_PATTERN.test(filename);
+}

package/scripts/shared/yaml-parser.ts

@@ -0,0 +1,55 @@
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+
+/**
+ * Safely parses YAML frontmatter from markdown content
+ * Uses SAFE_SCHEMA to prevent code execution via malicious YAML
+ */
+export function parseFrontmatter(content: string): Record<string, any> {
+  const match = content.match(/^---\n([\s\S]+?)\n---/);
+  if (!match) {
+    return {};
+  }
+
+  try {
+    // Use CORE_SCHEMA (safer than DEFAULT_SCHEMA, blocks !!python/object etc)
+    const parsed = yamlLoad(match[1], {
+      schema: yamlLoad.CORE_SCHEMA,
+      json: true, // Only allow JSON-compatible subset
+    });
+
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Invalid frontmatter structure - must be object");
+    }
+
+    return parsed as Record<string, any>;
+  } catch (err: any) {
+    throw new Error(`Frontmatter parse error: ${err.message}`);
+  }
+}
+
+/**
+ * Extracts body content (everything after frontmatter)
+ */
+export function extractBody(content: string): string {
+  const match = content.match(/^---\n[\s\S]+?\n---\n([\s\S]*)$/);
+  return match ? match[1] : content;
+}
+
+/**
+ * Safely stringifies frontmatter to YAML
+ */
+export function stringifyFrontmatter(obj: Record<string, any>): string {
+  return yamlDump(obj, {
+    schema: yamlDump.CORE_SCHEMA,
+    noRefs: true, // Prevent circular references
+    lineWidth: -1, // Don't wrap lines
+  });
+}
+
+/**
+ * Reconstructs markdown file with frontmatter
+ */
+export function buildMarkdown(frontmatter: Record<string, any>, body: string): string {
+  const yaml = stringifyFrontmatter(frontmatter).trim();
+  return `---\n${yaml}\n---\n${body}`;
+}