create-zudo-doc 0.1.0

package/templates/features/claudeResources/files/plugins/claude-resources-plugin.mjs

@@ -0,0 +1,137 @@
+// zfb plugin module: claude-resources.
+//
+// Wires `runClaudeResourcesPreStep` (from
+// `@takazudo/zudo-doc/integrations/claude-resources`) into zfb's
+// `preBuild` lifecycle hook. Replaces the npm `prebuild`-script glue
+// in `scripts/zfb-prebuild.mjs` for this step (the script remains in
+// place during the merge window — T6 retires it).
+//
+// Why this shim exists (and is not the v2 integration module directly):
+//
+//   1. zfb's plugin host runs `node` without any TypeScript loader, so
+//      it cannot import `.ts` source files. The v2 integration package
+//      (`@takazudo/zudo-doc/integrations/claude-resources`) currently
+//      ships only TypeScript source through its `exports` map and has
+//      no build step.
+//
+//   2. The `runClaudeResourcesPreStep` runner pulls in `gray-matter`,
+//      which performs a CJS `require("fs")` that esbuild's
+//      configuration-loader bundle (ESM-only) cannot satisfy. Loading
+//      it inline at the top of `zfb.config.ts` therefore breaks config
+//      parsing entirely.
+//
+// Both problems are solved by isolating the runner behind a child
+// process: this shim spawns `tsx` (the project's existing TS-aware
+// Node runner, pinned via `tsx` in `package.json`) on a tiny inline
+// script that imports the runner. tsx handles `.ts` resolution and
+// Node's CJS↔ESM interop for gray-matter; the parent plugin host stays
+// in plain Node and only sees a child-process exit code.
+//
+// Inline functions are not supported by zfb's plugin runtime — see
+// `@takazudo/zfb/plugins` source comment. This file is the plugin-host
+// equivalent once the npm script is retired (T6).
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
+
+// `tsx` is a workspace dependency of the host project and resolves to
+// `<projectRoot>/node_modules/.bin/tsx` from this file. We resolve the
+// binary explicitly so the shim does not depend on the parent shell's
+// `PATH` (the plugin host is spawned by zfb without sourcing the
+// user's profile — Node's `PATH` is whatever zfb itself was launched
+// with).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TSX_BIN = resolve(HERE, "..", "node_modules", ".bin", "tsx");
+
+/**
+ * Run the v2 claude-resources runner under tsx.
+ *
+ * Inlines a minimal ESM script via `tsx -e` so we don't have to ship a
+ * second `.ts` file just to host the call site. The runner returns a
+ * `{ claudemd, commands, skills, agents }` summary which we re-emit on
+ * the child's stdout — the parent (this shim) parses it and forwards
+ * the summary to the plugin host's logger.
+ */
+function runRunnerUnderTsx({ claudeDir, projectRoot, docsDir }) {
+  // The runner accepts `projectRoot` and `docsDir` as relative paths
+  // (resolved against `process.cwd()` in the runner). To insulate the
+  // child from whatever cwd zfb spawned us with, we set cwd explicitly
+  // and pass absolute paths through.
+  // tsx's `-e` flag emits CJS by default (it picks the format from the
+  // entry's extension, and an inline `-e` script has none), so we wrap
+  // the body in an `async`-IIFE rather than relying on top-level await.
+  const childScript = `
+    (async () => {
+      const { runClaudeResourcesPreStep } = await import("@takazudo/zudo-doc/integrations/claude-resources");
+      const result = await runClaudeResourcesPreStep({
+        claudeDir: ${JSON.stringify(claudeDir)},
+        projectRoot: ${JSON.stringify(projectRoot)},
+        docsDir: ${JSON.stringify(docsDir)},
+      });
+      process.stdout.write(JSON.stringify(result));
+    })().catch((err) => {
+      process.stderr.write(err && err.stack ? err.stack : String(err));
+      process.exit(1);
+    });
+  `;
+
+  return new Promise((resolveCall, reject) => {
+    const child = spawn(TSX_BIN, ["-e", childScript], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            `[${PLUGIN_NAME}] runner exited with code ${code}\n${stderr}`,
+          ),
+        );
+        return;
+      }
+      try {
+        resolveCall(JSON.parse(stdout));
+      } catch (err) {
+        reject(
+          new Error(
+            `[${PLUGIN_NAME}] failed to parse runner stdout: ${err.message}\nstdout: ${stdout}\nstderr: ${stderr}`,
+          ),
+        );
+      }
+    });
+  });
+}
+
+export default {
+  name: PLUGIN_NAME,
+  async preBuild(ctx) {
+    const claudeDir = ctx.options.claudeDir;
+    if (typeof claudeDir !== "string" || claudeDir.length === 0) {
+      throw new Error(
+        `[${PLUGIN_NAME}] preBuild: options.claudeDir must be a non-empty string (got ${JSON.stringify(claudeDir)})`,
+      );
+    }
+    const projectRootOpt = ctx.options.projectRoot;
+    const docsDirOpt = ctx.options.docsDir;
+    const result = await runRunnerUnderTsx({
+      claudeDir,
+      projectRoot:
+        typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
+      docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs",
+    });
+    // Surface a one-line summary so build logs make the migration
+    // observable (mirrors the `[zfb-prebuild]` lines from the legacy
+    // npm-script glue).
+    ctx.logger.info(
+      `claude-resources: ${result.claudemd} CLAUDE.md, ${result.commands} commands, ${result.skills} skills, ${result.agents} agents`,
+    );
+  },
+};

package/templates/features/claudeResources/files/src/integrations/claude-resources/__tests__/escape-for-mdx.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { escapeForMdx } from "../escape-for-mdx";
+
+describe("escapeForMdx", () => {
+  // ---------------------------------------------------------------------------
+  // Path-like angle bracket sequences (not self-closing JSX)
+  // ---------------------------------------------------------------------------
+
+  it("escapes path-like <name>/suffix sequences", () => {
+    expect(escapeForMdx("<foo>/bar")).toBe("&lt;foo&gt;/bar");
+  });
+
+  it("escapes path-like angle brackets in prose", () => {
+    expect(escapeForMdx("binary at <repo>/target/release/zfb")).toBe(
+      "binary at &lt;repo&gt;/target/release/zfb",
+    );
+  });
+
+  // ---------------------------------------------------------------------------
+  // Allowlisted HTML tags must pass through unchanged
+  // ---------------------------------------------------------------------------
+
+  it("preserves allowlisted HTML tags followed by a path separator", () => {
+    expect(escapeForMdx("<div>/path")).toBe("<div>/path");
+  });
+
+  // ---------------------------------------------------------------------------
+  // Self-closing non-allowlisted tags must still be escaped
+  // ---------------------------------------------------------------------------
+
+  it("escapes self-closing non-allowlisted component tags", () => {
+    expect(escapeForMdx("<Component />")).toMatch(/&lt;Component\s*\/&gt;/);
+  });
+});

package/templates/features/claudeResources/files/src/integrations/claude-resources/__tests__/generate.test.ts

@@ -0,0 +1,376 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import matter from "gray-matter";
+import { generateClaudeResourcesDocs } from "../generate";
+
+let tmpDir: string;
+let claudeDir: string;
+let docsDir: string;
+
+function createFixture() {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-res-test-"));
+
+  // .claude/ directory
+  claudeDir = path.join(tmpDir, ".claude");
+  docsDir = path.join(tmpDir, "docs");
+  fs.mkdirSync(docsDir, { recursive: true });
+
+  // Commands
+  const commandsDir = path.join(claudeDir, "commands");
+  fs.mkdirSync(commandsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(commandsDir, "test-cmd.md"),
+    '---\ndescription: "A test command"\n---\n\nThis is a test command body.',
+  );
+
+  // Skills
+  const skillDir = path.join(claudeDir, "skills", "test-skill");
+  fs.mkdirSync(path.join(skillDir, "references"), { recursive: true });
+  fs.mkdirSync(path.join(skillDir, "scripts"), { recursive: true });
+  fs.mkdirSync(path.join(skillDir, "assets"), { recursive: true });
+
+  fs.writeFileSync(
+    path.join(skillDir, "SKILL.md"),
+    '---\nname: test-skill\ndescription: "A test skill"\n---\n\nSkill instructions here.\n\nSee [references/guide.md](references/guide.md) for details.',
+  );
+  fs.writeFileSync(
+    path.join(skillDir, "references", "guide.md"),
+    "# Guide\n\nSome guide content",
+  );
+  fs.writeFileSync(
+    path.join(skillDir, "scripts", "run.sh"),
+    "#!/bin/bash\n# Run the test",
+  );
+  fs.writeFileSync(
+    path.join(skillDir, "assets", "template.md"),
+    "# Template\n\nA template",
+  );
+
+  // Agents
+  const agentsDir = path.join(claudeDir, "agents");
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(agentsDir, "test-agent.md"),
+    '---\nname: test-agent\ndescription: "A test agent"\nmodel: sonnet\n---\n\nAgent instructions here.',
+  );
+
+  // Root CLAUDE.md
+  fs.writeFileSync(
+    path.join(tmpDir, "CLAUDE.md"),
+    "# Project\n\nProject instructions",
+  );
+}
+
+describe("generateClaudeResourcesDocs", () => {
+  beforeEach(() => {
+    createFixture();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ---------------------------------------------------------------------------
+  // File structure tests
+  // ---------------------------------------------------------------------------
+
+  describe("file structure", () => {
+    it("generates correct directory structure", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      expect(fs.existsSync(path.join(docsDir, "claude"))).toBe(true);
+      expect(fs.existsSync(path.join(docsDir, "claude-md"))).toBe(true);
+      expect(fs.existsSync(path.join(docsDir, "claude-commands"))).toBe(true);
+      expect(fs.existsSync(path.join(docsDir, "claude-skills"))).toBe(true);
+      expect(fs.existsSync(path.join(docsDir, "claude-agents"))).toBe(true);
+    });
+
+    it("generates _category_.json with noPage for sub-categories", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const dirs = ["claude-md", "claude-commands", "claude-skills", "claude-agents"];
+      for (const dir of dirs) {
+        const catPath = path.join(docsDir, dir, "_category_.json");
+        expect(fs.existsSync(catPath)).toBe(true);
+
+        const cat = JSON.parse(fs.readFileSync(catPath, "utf8"));
+        expect(cat).toHaveProperty("label");
+        expect(cat).toHaveProperty("position");
+        expect(cat).toHaveProperty("description");
+        expect(cat.noPage).toBe(true);
+      }
+    });
+
+    it("generates skill as flat .mdx file", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const flatPath = path.join(docsDir, "claude-skills", "test-skill.mdx");
+      expect(fs.existsSync(flatPath)).toBe(true);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Content tests
+  // ---------------------------------------------------------------------------
+
+  describe("content", () => {
+    it("generates overview page with CategoryNav", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const overview = fs.readFileSync(
+        path.join(docsDir, "claude", "index.mdx"),
+        "utf8",
+      );
+      expect(overview).toContain('<CategoryNav categories={');
+    });
+
+    it("skill page has correct frontmatter", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const skillPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        "utf8",
+      );
+      const parsed = matter(skillPage);
+
+      expect(parsed.data.title).toBe("test-skill");
+      expect(parsed.data.description).toBe("A test skill");
+      expect(parsed.data.sidebar_label).toBe("test-skill");
+    });
+
+    it("skill page has file tree", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const skillPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        "utf8",
+      );
+
+      // Should contain tree-drawing characters
+      expect(skillPage).toContain("├── ");
+      expect(skillPage).toContain("└── ");
+      expect(skillPage).toContain("test-skill/");
+      expect(skillPage).toContain("SKILL.md");
+    });
+
+    it("skill page has links to sub-files that resolve correctly from the page URL", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const skillPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        "utf8",
+      );
+
+      // Links use ./<subpage> format (relative to the skill page URL which
+      // already includes the skill dir, e.g. /docs/claude-skills/test-skill/)
+      expect(skillPage).toContain("./ref-guide");
+      expect(skillPage).toContain("./asset-template");
+
+      // Must NOT contain the double-dir pattern ./<dir>/<subpage>
+      expect(skillPage).not.toContain("./test-skill/ref-guide");
+      expect(skillPage).not.toContain("./test-skill/asset-template");
+
+      // Each linked sub-page must exist as a generated flat .mdx file
+      // The file is flat (test-skill--ref-guide.mdx) but slug is nested
+      const linkPattern = /\]\(\.\/([\w-]+)\)/g;
+      let match;
+      while ((match = linkPattern.exec(skillPage)) !== null) {
+        const subPage = match[1];
+        const targetFile = path.join(
+          docsDir,
+          "claude-skills",
+          `test-skill--${subPage}.mdx`,
+        );
+        expect(
+          fs.existsSync(targetFile),
+          `Link target "test-skill--${subPage}.mdx" should exist`,
+        ).toBe(true);
+      }
+    });
+
+    it("skill body references/scripts/assets links are rewritten to doc site format", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const skillPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        "utf8",
+      );
+
+      // Body links like (references/guide.md) should be rewritten to (./ref-guide)
+      expect(skillPage).toContain("](./ref-guide)");
+      expect(skillPage).not.toContain("](references/guide.md)");
+    });
+
+    it("agent page has model badge", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const agentPage = fs.readFileSync(
+        path.join(docsDir, "claude-agents", "test-agent.mdx"),
+        "utf8",
+      );
+      expect(agentPage).toContain("**Model:** `sonnet`");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Sub-file page tests
+  // ---------------------------------------------------------------------------
+
+  describe("sub-file pages", () => {
+    it("generates unlisted reference page", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const refPage = path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx");
+      expect(fs.existsSync(refPage)).toBe(true);
+
+      const parsed = matter(fs.readFileSync(refPage, "utf8"));
+      expect(parsed.data.unlisted).toBe(true);
+    });
+
+    it("generates unlisted asset page for .md files", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const assetPage = path.join(docsDir, "claude-skills", "test-skill--asset-template.mdx");
+      expect(fs.existsSync(assetPage)).toBe(true);
+
+      const parsed = matter(fs.readFileSync(assetPage, "utf8"));
+      expect(parsed.data.unlisted).toBe(true);
+    });
+
+    it("does NOT generate page for non-.md scripts", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const scriptPage = path.join(docsDir, "claude-skills", "test-skill--script-run.mdx");
+      expect(fs.existsSync(scriptPage)).toBe(false);
+    });
+
+    it("sub-pages have custom slug for nested breadcrumbs", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const refPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        "utf8",
+      );
+      const parsed = matter(refPage);
+      expect(parsed.data.slug).toBe("claude-skills/test-skill/ref-guide");
+    });
+
+    it("reference page content is correct", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const refPage = fs.readFileSync(
+        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        "utf8",
+      );
+      const parsed = matter(refPage);
+
+      expect(parsed.data.title).toBe("Guide");
+      expect(parsed.content).toContain("Some guide content");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Category metadata tests
+  // ---------------------------------------------------------------------------
+
+  describe("category metadata", () => {
+    it("_category_.json positions are ordered correctly", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const readPos = (dir: string) => {
+        const cat = JSON.parse(
+          fs.readFileSync(path.join(docsDir, dir, "_category_.json"), "utf8"),
+        );
+        return cat.position;
+      };
+
+      expect(readPos("claude-md")).toBe(900);
+      expect(readPos("claude-commands")).toBe(901);
+      expect(readPos("claude-skills")).toBe(902);
+      expect(readPos("claude-agents")).toBe(903);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Return value test
+  // ---------------------------------------------------------------------------
+
+  describe("return value", () => {
+    it("returns correct counts", () => {
+      const result = generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      expect(result).toEqual({
+        claudemd: 1,
+        commands: 1,
+        skills: 1,
+        agents: 1,
+      });
+    });
+  });
+});

package/templates/features/claudeResources/files/src/integrations/claude-resources/escape-for-mdx.ts

@@ -0,0 +1,93 @@
+const htmlTags = new Set([
+  "div", "span", "p", "a", "img", "br", "hr", "ul", "ol", "li",
+  "h1", "h2", "h3", "h4", "h5", "h6", "code", "pre", "blockquote",
+  "table", "tr", "td", "th", "thead", "tbody", "tfoot", "colgroup", "col",
+  "strong", "em", "b", "i", "u", "s", "del", "ins", "sub", "sup",
+  "details", "summary", "figure", "figcaption", "mark", "small",
+  "cite", "q", "abbr", "dfn", "time", "var", "samp", "kbd",
+  "section", "article", "aside", "header", "footer", "nav", "main",
+  "form", "input", "button", "select", "option", "textarea", "label",
+  "fieldset", "legend", "dl", "dt", "dd", "caption",
+]);
+
+/**
+ * Escape angle brackets and curly braces in content for MDX compatibility.
+ * Preserves content inside code blocks (``` ... ```) and inline code (` ... `).
+ * Handles 3+ backtick fenced blocks correctly.
+ */
+export function escapeForMdx(content: string): string {
+  // Extract code blocks (supports 3+ backtick fences via backreference)
+  const codeBlocks: string[] = [];
+  const placeholder = "\x00CODEBLOCK_";
+  const codeBlockRegex = /(`{3,})[^\n]*\n[\s\S]*?\1/g;
+  const withPlaceholders = content.replace(codeBlockRegex, (match) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(match);
+    return `${placeholder}${idx}\x00`;
+  });
+  const parts = withPlaceholders.split(
+    new RegExp(`(${placeholder}\\d+\x00)`, "g"),
+  );
+
+  return parts
+    .map((part) => {
+      const placeholderMatch = part.match(
+        new RegExp(`^${placeholder}(\\d+)\x00$`),
+      );
+      if (placeholderMatch) return codeBlocks[Number(placeholderMatch[1])];
+
+      // For non-code-block text, split on inline code to preserve it.
+      // Supports multi-backtick inline code (`` `code` ``, ``` ``code`` ```).
+      const inlineCodeRegex = /(`{1,3})(?!`)([\s\S]*?[^`])\1(?!`)/g;
+      const inlineCodes: string[] = [];
+      const inlinePlaceholder = "\x00INLINE_";
+      const withInlinePlaceholders = part.replace(
+        inlineCodeRegex,
+        (match) => {
+          const idx = inlineCodes.length;
+          inlineCodes.push(match);
+          return `${inlinePlaceholder}${idx}\x00`;
+        },
+      );
+
+      let escaped = withInlinePlaceholders
+        // Escape opening tags: <Name>, <Name attr="val">
+        .replace(
+          /<([A-Za-z][A-Za-z0-9_-]*)(\s[^>]*)?>/g,
+          (match, name: string) => {
+            if (htmlTags.has(name.toLowerCase())) return match;
+            return match.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+          },
+        )
+        // Escape closing tags: </Name>
+        .replace(
+          /<\/([A-Za-z][A-Za-z0-9_-]*)>/g,
+          (match, name: string) => {
+            if (htmlTags.has(name.toLowerCase())) return match;
+            return `&lt;/${name}&gt;`;
+          },
+        )
+        // Escape self-closing tags: <Name />
+        .replace(
+          /<([A-Za-z][A-Za-z0-9_-]*)(\s[^>]*)?\s*\/>/g,
+          (match, name: string) => {
+            if (htmlTags.has(name.toLowerCase())) return match;
+            return match.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+          },
+        )
+        .replace(/<(-+|=+)/g, "&lt;$1")
+        .replace(/<(\d)/g, "&lt;$1")
+        // Escape curly braces (MDX interprets them as JSX expressions)
+        .replace(/\{/g, "&#123;")
+        .replace(/\}/g, "&#125;");
+
+      // Restore inline code placeholders
+      escaped = escaped.replace(
+        new RegExp(`${inlinePlaceholder}(\\d+)\x00`, "g"),
+        (_, idx: string) => inlineCodes[Number(idx)],
+      );
+
+      return escaped;
+    })
+    .join("");
+}