@stritti/vitepress-plugin-openspec 0.7.0 → 0.8.0

package/dist/index.js

@@ -1,14 +1,212 @@
 import fs from 'fs';
 import path from 'path';
 import pc from 'picocolors';
-import yaml from 'js-yaml';
+import { load } from 'js-yaml';
 
 // src/plugin.ts
+var PLUGIN_NAME = "vitepress-plugin-openspec";
+function prefix(color) {
+  return pc.bold(color(`[${PLUGIN_NAME}]`));
+}
+function logWarn(message) {
+  console.warn(`${prefix(pc.yellow)} ${message}`);
+}
+function logInfo(message) {
+  console.log(`${prefix(pc.cyan)} ${message}`);
+}
+function logError(message) {
+  console.error(`${prefix(pc.red)} ${message}`);
+}
+var GENERATED_MARKER = "# Generated by vitepress-plugin-openspec";
+function looksLikeOpenSpecDir(dir) {
+  const gitignore = path.join(dir, ".gitignore");
+  if (fs.existsSync(gitignore)) {
+    try {
+      if (fs.readFileSync(gitignore, "utf-8").startsWith(GENERATED_MARKER)) return false;
+    } catch {
+    }
+  }
+  if (fs.existsSync(path.join(dir, "project.md"))) return "strong";
+  if (fs.existsSync(path.join(dir, "config.yaml")) || fs.existsSync(path.join(dir, "config.yml"))) return "strong";
+  const changesDir = path.join(dir, "changes");
+  if (fs.existsSync(changesDir)) {
+    try {
+      for (const entry of fs.readdirSync(changesDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() && !entry.name.endsWith(".yaml")) continue;
+        const marker = path.join(changesDir, entry.name, ".openspec.yaml");
+        const yaml = path.join(changesDir, `${entry.name}.yaml`);
+        if (fs.existsSync(marker) || fs.existsSync(yaml)) return "strong";
+      }
+    } catch {
+    }
+  }
+  const specsDir = path.join(dir, "specs");
+  if (fs.existsSync(specsDir)) {
+    try {
+      for (const entry of fs.readdirSync(specsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (fs.existsSync(path.join(specsDir, entry.name, "spec.md"))) return "strong";
+      }
+    } catch {
+    }
+  }
+  const archiveDir = path.join(changesDir, "archive");
+  if (fs.existsSync(archiveDir)) {
+    try {
+      if (fs.readdirSync(archiveDir, { withFileTypes: true }).some((e) => e.isDirectory())) return "weak";
+    } catch {
+    }
+  }
+  return false;
+}
+function findOpenSpecDir(start, generatedOutputDir) {
+  let current = path.resolve(start);
+  for (; ; ) {
+    const candidate = path.join(current, "openspec");
+    if (fs.existsSync(candidate)) {
+      const match = looksLikeOpenSpecDir(candidate);
+      if (match === "weak" && generatedOutputDir && realPath(candidate) === realPath(generatedOutputDir)) {
+        const parent2 = path.dirname(current);
+        if (parent2 === current) return void 0;
+        current = parent2;
+        continue;
+      }
+      if (match === "strong" || match === "weak") return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return void 0;
+    current = parent;
+  }
+}
+function realPath(target) {
+  let current = path.resolve(target);
+  const suffix = [];
+  for (; ; ) {
+    if (fs.existsSync(current)) break;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(target);
+    suffix.unshift(path.basename(current));
+    current = parent;
+  }
+  try {
+    current = fs.realpathSync(current);
+  } catch {
+    return path.resolve(target);
+  }
+  return suffix.length ? path.join(current, ...suffix) : current;
+}
+var srcDirCache = /* @__PURE__ */ new Map();
+function detectSrcDir(cwd) {
+  const key = path.resolve(cwd);
+  if (srcDirCache.has(key)) return srcDirCache.get(key);
+  const result = resolveSrcDir(key);
+  srcDirCache.set(key, result);
+  return result;
+}
+function resolveSrcDir(cwd) {
+  if (path.basename(cwd) === ".vitepress") return path.dirname(cwd);
+  if (fs.existsSync(path.join(cwd, ".vitepress"))) return cwd;
+  const matches = [];
+  try {
+    for (const entry of fs.readdirSync(cwd, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const subDir = path.join(cwd, entry.name);
+      if (fs.existsSync(path.join(subDir, ".vitepress"))) matches.push(subDir);
+    }
+  } catch {
+  }
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const docsMatch = matches.find((m) => path.basename(m) === "docs");
+    if (docsMatch) return docsMatch;
+    logWarn(
+      `Multiple VitePress source directories found (${matches.map((m) => path.relative(cwd, m)).join(", ")}) \u2014 pass an explicit \`srcDir\` option. Skipping page generation.`
+    );
+    return void 0;
+  }
+  return cwd;
+}
+function detectVitePressRoot(cwd) {
+  const srcDir = detectSrcDir(cwd);
+  return srcDir && fs.existsSync(path.join(srcDir, ".vitepress")) ? srcDir : cwd;
+}
+
+// src/lib/options.ts
+function resolveOptions(userOptions = {}, fallbackSrcDir) {
+  const outDir = (userOptions.outDir ?? "openspec").replace(/\\/g, "/");
+  if (path.isAbsolute(outDir) || outDir === "" || outDir === "." || outDir === "..") {
+    throw new Error(
+      `[vitepress-plugin-openspec] Invalid outDir "${outDir}": it must be a relative path inside the VitePress srcDir.`
+    );
+  }
+  const srcDir = userOptions.srcDir ?? fallbackSrcDir ?? detectSrcDir(process.cwd()) ?? process.cwd();
+  const absoluteSrcDir = path.resolve(srcDir);
+  const absoluteOutDir = path.resolve(absoluteSrcDir, outDir);
+  const rel = path.relative(absoluteSrcDir, absoluteOutDir);
+  if (rel.startsWith("..") || path.isAbsolute(rel) || rel === "") {
+    throw new Error(
+      `[vitepress-plugin-openspec] Invalid outDir "${outDir}": it resolves outside the VitePress srcDir.`
+    );
+  }
+  const specDir = userOptions.specDir ?? findOpenSpecDir(process.cwd(), absoluteOutDir) ?? "./openspec";
+  return {
+    specDir: path.resolve(specDir),
+    outDir,
+    srcDir: absoluteSrcDir,
+    absoluteOutDir
+  };
+}
+var ALWAYS_GENERATED_BASENAMES = /* @__PURE__ */ new Set(["index.md", ".gitignore", ".openspec-manifest.json"]);
+var ARTIFACT_BASENAMES = /* @__PURE__ */ new Set(["proposal.md", "design.md", "tasks.md"]);
+var generatedDestCache = /* @__PURE__ */ new Map();
+function generatedDestinations(absoluteOutDir) {
+  const cached = generatedDestCache.get(absoluteOutDir);
+  if (cached) return cached;
+  const set = /* @__PURE__ */ new Set();
+  for (const entry of readManifest(absoluteOutDir)) {
+    set.add(path.resolve(absoluteOutDir, entry));
+  }
+  generatedDestCache.set(absoluteOutDir, set);
+  return set;
+}
+function invalidateGeneratedDestinations(absoluteOutDir) {
+  generatedDestCache.delete(absoluteOutDir);
+}
+function isInside(parent, child) {
+  const rel = path.relative(parent, child);
+  return !(rel.startsWith("..") || path.isAbsolute(rel));
+}
+function classifyLayout(options) {
+  if (options.specDir === options.absoluteOutDir) return "equal";
+  if (isInside(options.specDir, options.absoluteOutDir)) return "out-inside-spec";
+  if (isInside(options.absoluteOutDir, options.specDir)) return "spec-inside-out";
+  return "disjoint";
+}
+function isPluginGeneratedFile(options, absFile) {
+  if (!isInside(options.absoluteOutDir, absFile)) return false;
+  if (generatedDestinations(options.absoluteOutDir).has(path.resolve(absFile))) return true;
+  const base = path.basename(absFile);
+  switch (classifyLayout(options)) {
+    case "equal":
+      return ALWAYS_GENERATED_BASENAMES.has(base);
+    case "out-inside-spec":
+      return ALWAYS_GENERATED_BASENAMES.has(base) && !isInside(options.specDir, absFile);
+    case "disjoint":
+      return ALWAYS_GENERATED_BASENAMES.has(base) || ARTIFACT_BASENAMES.has(base);
+    case "spec-inside-out":
+      return !isInside(options.specDir, absFile) && (ALWAYS_GENERATED_BASENAMES.has(base) || ARTIFACT_BASENAMES.has(base));
+  }
+}
+function isSourceArtifactEvent(options, absFile) {
+  if (!isInside(options.specDir, absFile)) return false;
+  return !isPluginGeneratedFile(options, absFile);
+}
+var ARTIFACT_NAMES = ["proposal", "design", "tasks"];
 function readOpenSpecYaml(dir) {
   const yamlPath = path.join(dir, ".openspec.yaml");
   if (!fs.existsSync(yamlPath)) return {};
   try {
-    return yaml.load(fs.readFileSync(yamlPath, "utf-8")) ?? {};
+    return load(fs.readFileSync(yamlPath, "utf-8")) ?? {};
   } catch {
     return {};
   }
@@ -57,11 +255,10 @@ function formatDate(val) {
   return String(val);
 }
 function readArtifacts(dir) {
-  const artifacts = [];
-  for (const name of ["proposal", "design", "tasks"]) {
-    if (fs.existsSync(path.join(dir, `${name}.md`))) artifacts.push(name);
-  }
-  return artifacts;
+  return ARTIFACT_NAMES.filter((name) => fs.existsSync(path.join(dir, `${name}.md`)));
+}
+function isDirectory(dir, name) {
+  return fs.existsSync(path.join(dir, name, ".openspec.yaml"));
 }
 function readOpenSpecFolder(dir) {
   const resolved = path.resolve(dir);
@@ -90,7 +287,7 @@ function readOpenSpecFolder(dir) {
     for (const entry of fs.readdirSync(changesDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name === "archive") continue;
       const changeDir = path.join(changesDir, entry.name);
-      if (!fs.existsSync(path.join(changeDir, ".openspec.yaml"))) continue;
+      if (!isDirectory(changeDir, ".")) continue;
       const meta = readOpenSpecYaml(changeDir);
       changes.push({
         name: entry.name,
@@ -107,23 +304,52 @@ function readOpenSpecFolder(dir) {
     for (const entry of fs.readdirSync(archiveDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const changeDir = path.join(archiveDir, entry.name);
-      const match = entry.name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
-      const archivedDate = match?.[1];
-      const name = match?.[2] ?? entry.name;
       const meta = readOpenSpecYaml(changeDir);
+      const match = entry.name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
       archivedChanges.push({
-        name,
+        name: match?.[2] ?? entry.name,
         title: meta.title ? String(meta.title) : void 0,
         dir: changeDir,
         artifacts: readArtifacts(changeDir),
         createdDate: formatDate(meta.created),
-        archivedDate,
+        archivedDate: match?.[1],
         archiveFolderName: entry.name
       });
     }
   }
   return { dir: resolved, specs, changes, archivedChanges };
 }
+function rewriteRelativeLinks(content, srcFilePath, openspecRootDir, outDir) {
+  const srcDir = path.dirname(srcFilePath);
+  return content.replace(
+    /(\[[^\]]*\])\(([^)]+)\)/g,
+    (_match, linkText, urlPart) => {
+      const titleMatch = urlPart.match(/^(.+?)(\s+["'][^"']*["'])?\s*$/);
+      if (!titleMatch) return _match;
+      const rawUrl = titleMatch[1].trim();
+      const title = titleMatch[2] ?? "";
+      if (!rawUrl || rawUrl.startsWith("http://") || rawUrl.startsWith("https://") || rawUrl.startsWith("//") || rawUrl.startsWith("/") || rawUrl.startsWith("#") || rawUrl.startsWith("mailto:") || rawUrl.startsWith("tel:")) {
+        return _match;
+      }
+      const hashIdx = rawUrl.indexOf("#");
+      const urlWithoutFragment = hashIdx >= 0 ? rawUrl.slice(0, hashIdx) : rawUrl;
+      const fragment = hashIdx >= 0 ? rawUrl.slice(hashIdx) : "";
+      if (!urlWithoutFragment) {
+        return _match;
+      }
+      const resolvedPath = path.resolve(srcDir, urlWithoutFragment);
+      const relToOpenspec = path.relative(openspecRootDir, resolvedPath);
+      if (relToOpenspec.startsWith("..") || path.isAbsolute(relToOpenspec)) {
+        return _match;
+      }
+      const vitePath = relToOpenspec.replace(/\.md$/, "").replace(/\\/g, "/");
+      const absoluteLink = `/${outDir}/${vitePath}${fragment}`;
+      return `${linkText}(${absoluteLink}${title})`;
+    }
+  );
+}
+
+// src/lib/markdown.ts
 function extractSpecDescription(content) {
   const reqMatch = content.match(/^### Requirement:[^\n]*\n+([\s\S]*?)(?=\n#{1,4} |\n*$)/m);
   if (!reqMatch) return void 0;
@@ -136,7 +362,7 @@ function extractSpecDescription(content) {
     const cut = sentence.lastIndexOf(" ", 160);
     sentence = (cut > 0 ? sentence.slice(0, cut) : sentence.slice(0, 160)) + "\u2026";
   }
-  return sentence.replace(/"/g, '\\"');
+  return sentence.replace(/([\\"])/g, "\\$1");
 }
 function stripDeltaMarkers(content) {
   const stripped = content.split("\n").filter((line) => !/^## (ADDED|MODIFIED|REMOVED) Requirements\s*$/.test(line)).join("\n");
@@ -165,6 +391,11 @@ function transformScenarios(content) {
   if (inScenario) result.push(":::");
   return result.join("\n");
 }
+function specTitle(spec) {
+  return spec.title ?? humanizeLabel(spec.name);
+}
+
+// src/lib/pages.ts
 function generateSpecPage(spec) {
   const description = extractSpecDescription(spec.content);
   const transformed = transformScenarios(stripDeltaMarkers(spec.content));
@@ -175,7 +406,7 @@ function generateSpecPage(spec) {
     lines.push("---");
     lines.push("");
   }
-  lines.push(`# ${spec.title ?? humanizeLabel(spec.name)}`);
+  lines.push(`# ${specTitle(spec)}`);
   lines.push("");
   lines.push(transformed.trimEnd());
   lines.push("");
@@ -191,7 +422,7 @@ function generateSpecsIndexPage(specs, outDir) {
     lines.push("*No specifications defined yet.*");
   } else {
     for (const spec of specs) {
-      lines.push(`- [${spec.title ?? humanizeLabel(spec.name)}](/${outDir}/specs/${spec.name}/)`);
+      lines.push(`- [${specTitle(spec)}](/${outDir}/specs/${spec.name}/)`);
     }
   }
   lines.push("");
@@ -211,10 +442,10 @@ function generateChangeIndexPage(change, outDir) {
   }
   lines.push("## Artifacts");
   lines.push("");
-  const prefix = change.archiveFolderName ? `/${outDir}/changes/archive/${change.archiveFolderName}` : `/${outDir}/changes/${change.name}`;
+  const prefix2 = change.archiveFolderName ? `/${outDir}/changes/archive/${change.archiveFolderName}` : `/${outDir}/changes/${change.name}`;
   for (const artifact of change.artifacts) {
     const label = artifact.charAt(0).toUpperCase() + artifact.slice(1);
-    lines.push(`- [${label}](${prefix}/${artifact})`);
+    lines.push(`- [${label}](${prefix2}/${artifact})`);
   }
   lines.push("");
   return lines.join("\n");
@@ -247,46 +478,176 @@ function generateChangesIndexPage(folder, outDir) {
   lines.push("");
   return lines.join("\n");
 }
-function rewriteRelativeLinks(content, srcFilePath, openspecRootDir, outDir) {
-  const srcDir = path.dirname(srcFilePath);
-  return content.replace(
-    /(\[[^\]]*\])\(([^)]+)\)/g,
-    (_match, linkText, urlPart) => {
-      const titleMatch = urlPart.match(/^(.+?)(\s+["'][^"']*["'])?\s*$/);
-      if (!titleMatch) return _match;
-      const rawUrl = titleMatch[1].trim();
-      const title = titleMatch[2] ?? "";
-      if (!rawUrl || rawUrl.startsWith("http://") || rawUrl.startsWith("https://") || rawUrl.startsWith("//") || rawUrl.startsWith("/") || rawUrl.startsWith("#") || rawUrl.startsWith("mailto:") || rawUrl.startsWith("tel:")) {
-        return _match;
-      }
-      const hashIdx = rawUrl.indexOf("#");
-      const urlWithoutFragment = hashIdx >= 0 ? rawUrl.slice(0, hashIdx) : rawUrl;
-      const fragment = hashIdx >= 0 ? rawUrl.slice(hashIdx) : "";
-      if (!urlWithoutFragment) {
-        return _match;
-      }
-      const resolvedPath = path.resolve(srcDir, urlWithoutFragment);
-      const relToOpenspec = path.relative(openspecRootDir, resolvedPath);
-      if (relToOpenspec.startsWith("..") || path.isAbsolute(relToOpenspec)) {
-        return _match;
+function generateRootIndexPage(outDir) {
+  return [
+    "# Project Documentation",
+    "",
+    "This section is generated from the project's [OpenSpec](https://openspec.dev/) folder.",
+    "OpenSpec is a lightweight, file-based workflow for spec-driven development \u2014",
+    "it structures your project's capability specifications and change proposals as plain Markdown files.",
+    "",
+    `- [Specifications](/${outDir}/specs/) \u2014 canonical capability specs`,
+    `- [Changes](/${outDir}/changes/) \u2014 active and archived change proposals`,
+    ""
+  ].join("\n");
+}
+
+// src/lib/generator.ts
+var MANIFEST_FILE = ".openspec-manifest.json";
+var GITIGNORE_CONTENT = "# Generated by vitepress-plugin-openspec \u2014 do not commit generated files.\n*\n!.gitignore\n";
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function toRel(absoluteOutDir, filePath) {
+  return path.relative(absoluteOutDir, filePath).split(path.sep).join("/");
+}
+function pruneEmptyDirs(rootDir, startDir) {
+  let dir = startDir;
+  while (dir.startsWith(rootDir) && dir !== rootDir) {
+    try {
+      if (fs.readdirSync(dir).length > 0) break;
+      fs.rmdirSync(dir);
+    } catch {
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+}
+function cleanupPreviousManifest(rootDir) {
+  const manifestPath = path.join(rootDir, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return [];
+  let previous = [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    if (Array.isArray(parsed)) previous = parsed.filter((f) => typeof f === "string");
+  } catch {
+    return [];
+  }
+  const retained = [];
+  for (const entry of previous) {
+    const entryPath = path.resolve(rootDir, entry);
+    const rel = path.relative(rootDir, entryPath);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) continue;
+    try {
+      if (fs.existsSync(entryPath)) {
+        fs.rmSync(entryPath);
+        pruneEmptyDirs(rootDir, path.dirname(entryPath));
       }
-      const vitePath = relToOpenspec.replace(/\.md$/, "").replace(/\\/g, "/");
-      const absoluteLink = `/${outDir}/${vitePath}${fragment}`;
-      return `${linkText}(${absoluteLink}${title})`;
+    } catch {
+      retained.push(entry);
     }
-  );
+  }
+  return retained;
+}
+function readManifest(rootDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(rootDir, MANIFEST_FILE), "utf-8"));
+    if (Array.isArray(parsed)) return parsed.filter((f) => typeof f === "string");
+  } catch {
+  }
+  return [];
+}
+function writeManifest(files, rootDir) {
+  const manifestPath = path.join(rootDir, MANIFEST_FILE);
+  try {
+    writeFile(manifestPath, JSON.stringify(files, null, 2));
+    invalidateGeneratedDestinations(rootDir);
+  } catch {
+  }
+}
+function renderChangePages(change, options, isArchived) {
+  const subPath = isArchived ? path.join("changes", "archive", change.archiveFolderName ?? change.name) : path.join("changes", change.name);
+  const changeOutDir = path.join(options.absoluteOutDir, subPath);
+  const files = [];
+  files.push({
+    rel: toRel(options.absoluteOutDir, path.join(changeOutDir, "index.md")),
+    content: generateChangeIndexPage(change, options.outDir)
+  });
+  for (const artifact of change.artifacts) {
+    const srcFile = path.join(change.dir, `${artifact}.md`);
+    const destFile = path.join(changeOutDir, `${artifact}.md`);
+    if (path.resolve(srcFile) === path.resolve(destFile)) continue;
+    const content = fs.readFileSync(srcFile, "utf-8");
+    files.push({
+      rel: toRel(options.absoluteOutDir, destFile),
+      content: rewriteRelativeLinks(content, srcFile, options.specDir, options.outDir)
+    });
+  }
+  return files;
+}
+function renderAllPages(options) {
+  const folder = readOpenSpecFolder(options.specDir);
+  const files = [];
+  for (const spec of folder.specs) {
+    const dest = path.join(options.absoluteOutDir, "specs", spec.name, "index.md");
+    files.push({ rel: toRel(options.absoluteOutDir, dest), content: generateSpecPage(spec) });
+  }
+  files.push({
+    rel: "specs/index.md",
+    content: generateSpecsIndexPage(folder.specs, options.outDir)
+  });
+  for (const change of folder.changes) {
+    files.push(...renderChangePages(change, options, false));
+  }
+  for (const change of folder.archivedChanges) {
+    files.push(...renderChangePages(change, options, true));
+  }
+  files.push({
+    rel: "changes/index.md",
+    content: generateChangesIndexPage(folder, options.outDir)
+  });
+  files.push({
+    rel: "index.md",
+    content: generateRootIndexPage(options.outDir)
+  });
+  return files;
+}
+function generatePages(options) {
+  if (!fs.existsSync(options.specDir)) {
+    logWarn(
+      `openspec directory not found: ${path.relative(options.srcDir, options.specDir)} \u2014 skipping page generation`
+    );
+    const retained2 = cleanupPreviousManifest(options.absoluteOutDir);
+    if (retained2.length > 0 || fs.existsSync(options.absoluteOutDir)) {
+      writeManifest(retained2, options.absoluteOutDir);
+    }
+    return false;
+  }
+  let files;
+  try {
+    files = renderAllPages(options);
+  } catch (err) {
+    logError(`Failed to process openspec directory "${options.specDir}": ${String(err)}`);
+    return false;
+  }
+  const retained = cleanupPreviousManifest(options.absoluteOutDir);
+  try {
+    writeFile(path.join(options.absoluteOutDir, ".gitignore"), GITIGNORE_CONTENT);
+    for (const file of files) {
+      writeFile(path.join(options.absoluteOutDir, file.rel), file.content);
+    }
+    writeManifest([...files.map((f) => f.rel), ...retained], options.absoluteOutDir);
+  } catch (err) {
+    logError(`Failed to write openspec pages: ${String(err)}`);
+    return false;
+  }
+  logInfo(`Generated docs from ${options.specDir}: ${files.length} file(s)`);
+  return true;
 }
 function changeItems(change, outDir, isArchived = false) {
-  const prefix = isArchived ? `/${outDir}/changes/archive/${change.archiveFolderName}` : `/${outDir}/changes/${change.name}`;
+  const prefix2 = isArchived ? `/${outDir}/changes/archive/${change.archiveFolderName}` : `/${outDir}/changes/${change.name}`;
   return change.artifacts.map((a) => ({
     text: a.charAt(0).toUpperCase() + a.slice(1),
-    link: `${prefix}/${a}`
+    link: `${prefix2}/${a}`
   }));
 }
 function generateOpenSpecSidebar(specDir, options = {}) {
   const outDir = options.outDir ?? "openspec";
   if (!fs.existsSync(path.resolve(specDir))) {
-    console.warn(`[vitepress-plugin-openspec] openspec directory not found: ${path.relative(process.cwd(), path.resolve(specDir))} \u2014 skipping sidebar generation`);
+    logWarn(
+      `openspec directory not found: ${path.relative(process.cwd(), path.resolve(specDir))} \u2014 skipping sidebar generation`
+    );
     return [];
   }
   const folder = readOpenSpecFolder(specDir);
@@ -296,7 +657,7 @@ function generateOpenSpecSidebar(specDir, options = {}) {
     collapsed: false,
     items: [
       { text: "Overview", link: `/${outDir}/specs/` },
-      ...folder.specs.map((s) => ({ text: s.title ?? humanizeLabel(s.name), link: `/${outDir}/specs/${s.name}/` }))
+      ...folder.specs.map((s) => ({ text: specTitle(s), link: `/${outDir}/specs/${s.name}/` }))
     ]
   });
   groups.push({
@@ -327,7 +688,9 @@ function generateOpenSpecSidebar(specDir, options = {}) {
 function openspecNav(specDir, options = {}) {
   const outDir = options.outDir ?? "openspec";
   if (!fs.existsSync(path.resolve(specDir))) {
-    console.warn(`[vitepress-plugin-openspec] openspec directory not found: ${path.relative(process.cwd(), path.resolve(specDir))} \u2014 skipping nav generation`);
+    logWarn(
+      `openspec directory not found: ${path.relative(process.cwd(), path.resolve(specDir))} \u2014 skipping nav generation`
+    );
     return null;
   }
   return {
@@ -336,113 +699,151 @@ function openspecNav(specDir, options = {}) {
   };
 }
 
-// src/plugin.ts
-var PLUGIN_NAME = "vitepress-plugin-openspec";
-function writeFile(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, "utf-8");
-}
-function generateOpenSpecPages(userOptions = {}) {
-  const specDir = userOptions.specDir ?? "./openspec";
-  const outDir = userOptions.outDir ?? "openspec";
-  const srcDir = userOptions.srcDir ?? process.cwd();
-  const absoluteOutDir = path.resolve(srcDir, outDir);
-  if (!fs.existsSync(path.resolve(specDir))) {
-    console.warn(
-      `${pc.bold(pc.yellow(`[${PLUGIN_NAME}]`))} openspec directory not found: ${path.relative(srcDir, path.resolve(specDir))} \u2014 skipping page generation`
-    );
-    return;
-  }
+// src/lib/dev-server.ts
+function readNavigationSignature(options) {
   try {
-    const folder = readOpenSpecFolder(specDir);
-    for (const spec of folder.specs) {
-      const dest = path.join(absoluteOutDir, "specs", spec.name, "index.md");
-      writeFile(dest, generateSpecPage(spec));
-    }
-    writeFile(
-      path.join(absoluteOutDir, "specs", "index.md"),
-      generateSpecsIndexPage(folder.specs, outDir)
-    );
-    for (const change of folder.changes) {
-      writeChangePage(change, absoluteOutDir, outDir, false, folder.dir);
-    }
-    for (const change of folder.archivedChanges) {
-      writeChangePage(change, absoluteOutDir, outDir, true, folder.dir);
-    }
-    writeFile(
-      path.join(absoluteOutDir, "changes", "index.md"),
-      generateChangesIndexPage(folder, outDir)
-    );
-    const rootIndex = [
-      "# Project Documentation",
-      "",
-      "This section is generated from the project's [OpenSpec](https://openspec.dev/) folder.",
-      "OpenSpec is a lightweight, file-based workflow for spec-driven development \u2014",
-      "it structures your project's capability specifications and change proposals as plain Markdown files.",
-      "",
-      `- [Specifications](/${outDir}/specs/) \u2014 canonical capability specs`,
-      `- [Changes](/${outDir}/changes/) \u2014 active and archived change proposals`,
-      ""
-    ].join("\n");
-    writeFile(path.join(absoluteOutDir, "index.md"), rootIndex);
-    writeFile(
-      path.join(absoluteOutDir, ".gitignore"),
-      "# Generated by vitepress-plugin-openspec \u2014 do not commit generated files.\n*\n!.gitignore\n"
-    );
-    console.log(
-      `${pc.bold(pc.cyan(`[${PLUGIN_NAME}]`))} Generated docs from ${pc.cyan(specDir)}: ${pc.green(String(folder.specs.length))} spec(s), ${pc.green(String(folder.changes.length))} change(s), ${pc.green(String(folder.archivedChanges.length))} archived`
-    );
-  } catch (err) {
-    console.error(
-      `${pc.bold(pc.red(`[${PLUGIN_NAME}]`))} Failed to process openspec directory "${specDir}": ${String(err)}`
-    );
+    const folder = readOpenSpecFolder(options.specDir);
+    return JSON.stringify({
+      specs: folder.specs.map((s) => [s.name, s.title ?? null]),
+      changes: folder.changes.map((c) => [c.name, c.title ?? null, c.createdDate ?? null, c.artifacts]),
+      archived: folder.archivedChanges.map((c) => [c.name, c.title ?? null, c.archivedDate ?? null, c.artifacts])
+    });
+  } catch {
+    return "unreadable";
   }
 }
+function createScheduler() {
+  let timer;
+  return {
+    schedule(options, server) {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = void 0;
+        generatePages(options);
+        invalidateGeneratedDestinations(options.absoluteOutDir);
+        server.ws.send({ type: "full-reload" });
+      }, 100);
+    },
+    cancel() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+    }
+  };
+}
+
+// src/plugin.ts
+function generateOpenSpecPages(userOptions = {}) {
+  const detectedSrcDir = userOptions.srcDir ?? detectSrcDir(process.cwd());
+  if (!detectedSrcDir) return false;
+  const options = resolveOptions(userOptions, detectedSrcDir);
+  return generatePages(options);
+}
 function openspec(userOptions = {}) {
+  let resolvedOptions;
+  let detachListeners;
   return {
     name: PLUGIN_NAME,
     enforce: "pre",
     configResolved(resolvedConfig) {
+      detachListeners?.();
       const vpConfig = resolvedConfig.vitepress;
       const srcDir = userOptions.srcDir ?? vpConfig?.srcDir ?? resolvedConfig.root ?? process.cwd();
-      generateOpenSpecPages({ ...userOptions, srcDir });
+      try {
+        resolvedOptions = resolveOptions(userOptions, srcDir);
+      } catch (err) {
+        logWarn(String(err));
+        return;
+      }
+      if (!fs.existsSync(resolvedOptions.specDir)) {
+        logWarn(
+          `openspec directory not found: ${resolvedOptions.specDir} \u2014 skipping page generation`
+        );
+        generatePages(resolvedOptions);
+        resolvedOptions = void 0;
+        return;
+      }
+      generatePages(resolvedOptions);
+    },
+    configureServer(server) {
+      if (!resolvedOptions || !fs.existsSync(resolvedOptions.specDir)) return;
+      const options = resolvedOptions;
+      server.watcher.add(options.specDir);
+      const scheduler = createScheduler();
+      let navigationSignature = readNavigationSignature(options);
+      const onWatchEvent = (event, file) => {
+        const absFile = path.resolve(file);
+        if (!isSourceArtifactEvent(options, absFile)) return;
+        const signature = readNavigationSignature(options);
+        const affectsNavigation = event !== "change" || signature !== navigationSignature;
+        if (affectsNavigation) {
+          scheduler.cancel();
+          navigationSignature = signature;
+          server.restart(true);
+        } else {
+          scheduler.schedule(options, server);
+        }
+      };
+      const onChange = (f) => onWatchEvent("change", f);
+      const onAdd = (f) => onWatchEvent("add", f);
+      const onUnlink = (f) => onWatchEvent("unlink", f);
+      server.watcher.on("change", onChange);
+      server.watcher.on("add", onAdd);
+      server.watcher.on("unlink", onUnlink);
+      detachListeners = () => {
+        scheduler.cancel();
+        server.watcher.off("change", onChange);
+        server.watcher.off("add", onAdd);
+        server.watcher.off("unlink", onUnlink);
+        server.httpServer?.removeListener("close", detachListeners);
+        detachListeners = void 0;
+      };
+      server.httpServer?.once("close", detachListeners);
+    },
+    closeBundle() {
+      detachListeners?.();
+      detachListeners = void 0;
     }
   };
 }
-function writeChangePage(change, absoluteOutDir, outDir, isArchived, openspecRootDir) {
-  const subPath = isArchived ? path.join("changes", "archive", `${change.archivedDate}-${change.name}`) : path.join("changes", change.name);
-  const changeOutDir = path.join(absoluteOutDir, subPath);
-  writeFile(path.join(changeOutDir, "index.md"), generateChangeIndexPage(change, outDir));
-  for (const artifact of change.artifacts) {
-    const srcFile = path.join(change.dir, `${artifact}.md`);
-    const destFile = path.join(changeOutDir, `${artifact}.md`);
-    const content = fs.readFileSync(srcFile, "utf-8");
-    writeFile(destFile, rewriteRelativeLinks(content, srcFile, openspecRootDir, outDir));
-  }
-}
 function withOpenSpec(config, options = {}) {
-  const specDir = options.specDir ?? "./openspec";
-  const outDir = options.outDir ?? "openspec";
-  const srcDir = options.srcDir ?? process.cwd();
-  generateOpenSpecPages({ specDir, outDir, srcDir });
+  const cwd = process.cwd();
+  const configSrcDir = typeof config.srcDir === "string" && config.srcDir ? path.resolve(detectVitePressRoot(cwd), config.srcDir) : void 0;
+  const detectedSrcDir = options.srcDir ?? configSrcDir ?? detectSrcDir(cwd);
   const result = { ...config };
+  const themeConfig = result.themeConfig ?? {};
+  if (Array.isArray(themeConfig.sidebar)) {
+    themeConfig.sidebar = { "/": themeConfig.sidebar };
+  }
+  result.themeConfig = themeConfig;
+  if (detectedSrcDir === void 0) return result;
+  let resolved;
+  try {
+    resolved = resolveOptions(options, detectedSrcDir);
+  } catch (err) {
+    logWarn(String(err));
+    return result;
+  }
+  const generated = generatePages(resolved);
   const vite = result.vite ?? {};
   const existingPlugins = vite.plugins ?? [];
-  result.vite = { ...vite, plugins: [...existingPlugins, openspec({ specDir, outDir, srcDir })] };
-  const themeConfig = result.themeConfig ?? {};
-  if (options.nav !== false) {
-    const navEntry = openspecNav(specDir, { outDir });
+  result.vite = { ...vite, plugins: [...existingPlugins, openspec({ ...options })] };
+  if (generated && options.nav !== false) {
+    const navEntry = openspecNav(resolved.specDir, {
+      outDir: resolved.outDir,
+      text: options.navText
+    });
     const existingNav = themeConfig.nav ?? [];
     themeConfig.nav = navEntry ? [navEntry, ...existingNav] : existingNav;
   }
-  if (options.sidebar !== false && !Array.isArray(themeConfig.sidebar)) {
-    const sidebarKey = `/${outDir}/`;
-    const existingSidebar = themeConfig.sidebar ?? {};
-    if (!existingSidebar[sidebarKey]) {
-      themeConfig.sidebar = {
-        ...existingSidebar,
-        [sidebarKey]: generateOpenSpecSidebar(specDir, { outDir })
-      };
+  const sidebarKey = `/${resolved.outDir}/`;
+  const existingSidebar = themeConfig.sidebar ?? {};
+  const pluginOwnsSidebarEntry = generated && options.sidebar !== false && !existingSidebar[sidebarKey];
+  if (pluginOwnsSidebarEntry) {
+    const items = generateOpenSpecSidebar(resolved.specDir, { outDir: resolved.outDir });
+    if (items.length > 0) {
+      themeConfig.sidebar = { ...existingSidebar, [sidebarKey]: items };
     }
   }
   result.themeConfig = themeConfig;