create-zudo-doc 0.1.0

package/templates/base/src/utils/git-info.ts

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+export interface GitInfo {
+  createdAt: string | null;
+  updatedAt: string | null;
+  author: string | null;
+}
+
+const gitInfoCache = new Map<string, GitInfo>();
+
+/** Resolve file path, trying .mdx/.md extensions if the path has no extension */
+function resolveFilePath(filePath: string): string {
+  if (existsSync(filePath)) return filePath;
+  for (const ext of [".mdx", ".md"]) {
+    const withExt = filePath + ext;
+    if (existsSync(withExt)) return withExt;
+  }
+  return filePath;
+}
+
+export function getGitInfo(filePath: string): GitInfo {
+  if (gitInfoCache.has(filePath)) {
+    return gitInfoCache.get(filePath)!;
+  }
+
+  const resolved = resolveFilePath(filePath);
+
+  try {
+    // Get all commit dates for this file (oldest last)
+    const allDates = execFileSync(
+      "git",
+      ["log", "--follow", "--format=%aI", "--", resolved],
+      { encoding: "utf-8" },
+    ).trim();
+
+    const dates = allDates ? allDates.split("\n") : [];
+    const createdAt = dates.length > 0 ? dates[dates.length - 1] : null;
+    const updatedAt = dates.length > 0 ? dates[0] : null;
+
+    const author = execFileSync(
+      "git",
+      ["log", "-1", "--format=%aN", "--", resolved],
+      { encoding: "utf-8" },
+    ).trim() || null;
+
+    const result = { createdAt, updatedAt, author };
+    gitInfoCache.set(filePath, result);
+    return result;
+  } catch {
+    const result = { createdAt: null, updatedAt: null, author: null };
+    gitInfoCache.set(filePath, result);
+    return result;
+  }
+}
+
+/** Format ISO date to human-readable, respecting locale */
+export function formatDate(isoDate: string, locale = "en"): string {
+  const d = new Date(isoDate);
+  const localeMap: Record<string, string> = {
+    en: "en-US",
+    ja: "ja-JP",
+    de: "de-DE",
+  };
+  return d.toLocaleDateString(localeMap[locale] ?? "en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}

package/templates/base/src/utils/github.ts

@@ -0,0 +1,19 @@
+import { settings } from "@/config/settings";
+
+function trimTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+export function buildGitHubRepoUrl(): string | null {
+  if (!settings.githubUrl) return null;
+  return trimTrailingSlash(settings.githubUrl as string);
+}
+
+export function buildGitHubSourceUrl(
+  contentDir: string,
+  entryId: string,
+): string | null {
+  const repoUrl = buildGitHubRepoUrl();
+  if (!repoUrl) return null;
+  return `${repoUrl}/blob/HEAD/${contentDir}/${entryId}`;
+}

package/templates/base/src/utils/header-right-items.ts

@@ -0,0 +1,38 @@
+import { settings } from "@/config/settings";
+import type { HeaderRightItem } from "@/config/settings-types";
+
+function isDesignTokenPanelEnabled(): boolean {
+  return Boolean(settings.designTokenPanel || settings.colorTweakPanel);
+}
+
+export function filterHeaderRightItems(
+  items: HeaderRightItem[],
+): HeaderRightItem[] {
+  return items.filter((item) => {
+    if (item.type === "trigger") {
+      if (item.trigger === "design-token-panel") {
+        return isDesignTokenPanelEnabled();
+      }
+      if (item.trigger === "ai-chat") {
+        return Boolean(settings.aiAssistant);
+      }
+    }
+
+    if (item.type === "component") {
+      if (item.component === "theme-toggle") {
+        return Boolean(settings.colorMode);
+      }
+      if (item.component === "language-switcher") {
+        return Object.keys(settings.locales).length > 0;
+      }
+      if (item.component === "version-switcher") {
+        return Boolean(settings.versions);
+      }
+      if (item.component === "github-link") {
+        return Boolean(settings.githubUrl);
+      }
+    }
+
+    return true;
+  });
+}

package/templates/base/src/utils/nav-scope.ts

@@ -0,0 +1,63 @@
+import { settings } from "@/config/settings";
+import type { NavNode } from "@/utils/docs";
+export type { HeaderNavItem } from "@/config/settings";
+
+/** Collect all categoryMatch strings from headerNav, including children (ordered). */
+export function getCategoryOrder(): string[] {
+  return settings.headerNav.flatMap((item) => {
+    const matches: string[] = [];
+    if (item.categoryMatch) matches.push(item.categoryMatch);
+    if (item.children) {
+      for (const child of item.children) {
+        if (child.categoryMatch) matches.push(child.categoryMatch);
+      }
+    }
+    return matches;
+  });
+}
+
+/**
+ * Given a doc's slug (e.g. "getting-started/introduction" or "claude-agents/doc-reviewer"),
+ * return the categoryMatch value of the headerNav item it belongs to.
+ */
+export function getNavSectionForSlug(slug: string): string | undefined {
+  const topCategory = slug.split("/")[0] ?? "";
+  const all = getCategoryOrder();
+
+  // First pass: find explicit matchers (not "!")
+  const explicitMatches = all.filter(
+    (cm) => cm !== "!" && topCategory.startsWith(cm),
+  );
+  if (explicitMatches.length > 0) {
+    // Longest prefix match wins
+    return explicitMatches.sort((a, b) => b.length - a.length)[0];
+  }
+
+  // Second pass: return the default ("!") matcher
+  const defaultItem = settings.headerNav.find(
+    (item) => item.categoryMatch === "!",
+  );
+  return defaultItem?.categoryMatch;
+}
+
+/**
+ * Filter top-level NavNodes by a headerNav categoryMatch value.
+ * - "!" means everything NOT claimed by explicit matchers
+ * - "claude" means nodes whose slug starts with "claude"
+ * - undefined means all nodes
+ */
+export function getNavSubtree(
+  tree: NavNode[],
+  categoryMatch?: string,
+): NavNode[] {
+  if (!categoryMatch) return tree;
+
+  if (categoryMatch === "!") {
+    const explicitPrefixes = getCategoryOrder().filter((cm) => cm !== "!");
+    return tree.filter(
+      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix)),
+    );
+  }
+
+  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+}

package/templates/base/src/utils/sidebar.ts

@@ -0,0 +1,104 @@
+import sidebars from "@/config/sidebars";
+import type { SidebarItem } from "@/config/sidebars";
+import type { NavNode, CategoryMeta } from "@/utils/docs";
+import { buildNavTree, findNode } from "@/utils/docs";
+import { getNavSubtree } from "@/utils/nav-scope";
+import type { Locale } from "@/config/i18n";
+import type { DocsEntry } from "@/types/docs-entry";
+
+/**
+ * Build sidebar nodes for a given nav section.
+ * If sidebar config exists for this section, use it.
+ * Otherwise fall back to auto-generated tree.
+ */
+export function buildSidebarForSection(
+  docs: DocsEntry[],
+  lang: Locale,
+  categoryMatch?: string,
+  categoryMeta?: Map<string, CategoryMeta>,
+): NavNode[] {
+  const tree = buildNavTree(docs, lang, categoryMeta);
+
+  // Check if there's a sidebar config for this section
+  const sectionKey = categoryMatch ?? "default";
+  const config = sidebars[sectionKey];
+
+  if (!config || config.length === 0) {
+    // Fall back to auto-generated
+    return getNavSubtree(tree, categoryMatch);
+  }
+
+  // Resolve config to nodes
+  return resolveItems(config, tree, lang);
+}
+
+function resolveItems(
+  items: SidebarItem[],
+  tree: NavNode[],
+  lang: Locale,
+): NavNode[] {
+  return items.flatMap((item) => resolveItem(item, tree, lang));
+}
+
+function resolveItem(
+  item: SidebarItem,
+  tree: NavNode[],
+  lang: Locale,
+): NavNode[] {
+  if (typeof item === "string") {
+    // String shorthand = doc reference (always rendered as leaf, children stripped)
+    const node = findNode(tree, item);
+    return node ? [{ ...node, children: [] }] : [];
+  }
+
+  switch (item.type) {
+    case "doc": {
+      const node = findNode(tree, item.id);
+      if (!node) return [];
+      // Doc references always render as leaves — strip children so they
+      // don't duplicate structure that the explicit config already defines.
+      return [{ ...node, children: [], ...(item.label ? { label: item.label } : {}) }];
+    }
+    case "link": {
+      return [
+        {
+          slug: `__link__${item.href}`,
+          label: item.label,
+          href: item.href,
+          position: 0,
+          hasPage: false,
+          children: [],
+        },
+      ];
+    }
+    case "category": {
+      const children = resolveItems(item.items, tree, lang);
+      if (item.sortOrder === "desc") {
+        children.reverse();
+      }
+      return [
+        {
+          slug: `__category__${item.label}`,
+          label: item.label,
+          position: 0,
+          hasPage: false,
+          href: undefined,
+          children,
+          sortOrder: item.sortOrder,
+          collapsed: item.collapsed,
+        },
+      ];
+    }
+    case "autogenerated": {
+      if (item.dirName) {
+        const node = findNode(tree, item.dirName);
+        return node ? node.children : [];
+      }
+      return tree;
+    }
+    default: {
+      const _exhaustive: never = item;
+      throw new Error(`Unhandled sidebar item type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}

package/templates/base/src/utils/slug.ts

@@ -0,0 +1,10 @@
+export function toRouteSlug(id: string): string {
+  return id.replace(/\/index$/, "");
+}
+
+export function toTitleCase(str: string): string {
+  return str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}

package/templates/base/src/utils/smart-break.tsx

@@ -0,0 +1,126 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { VNode } from "preact";
+
+/**
+ * Heuristic: does `text` look like a URL, filesystem path, or similar
+ * structure where inserting <wbr> after delimiters aids line-wrapping?
+ *
+ * Returns true for URLs (contain "://"), POSIX-style absolute/relative
+ * paths ("/", "./", "../"), Windows drive paths ("C:\\..." or "C:/..."),
+ * strings with 2+ slashes (or backslashes) between alphanumerics, and
+ * plausible domain-plus-slash strings.
+ *
+ * Returns false for empty input and prose-y hyphen/slash/dot combinations
+ * like "and/or", "well-known", "state-of-the-art", "1.2.3-beta.4", "UI/UX".
+ */
+export function isPathLike(text: string): boolean {
+  if (!text) return false;
+  if (text.includes("://")) return true;
+  // starts with "/", "./", or "../"
+  if (/^\.{0,2}\//.test(text)) return true;
+  // Windows drive letter paths, either backslash or forward slash
+  if (/^[A-Za-z]:[\\/]/.test(text)) return true;
+  // 2+ forward slashes appearing between alphanumeric runs
+  const forwardMatches = text.match(/[A-Za-z0-9]\/[A-Za-z0-9]/g);
+  if (forwardMatches && forwardMatches.length >= 2) return true;
+  // 2+ backslashes appearing between alphanumeric runs
+  const backMatches = text.match(/[A-Za-z0-9]\\[A-Za-z0-9]/g);
+  if (backMatches && backMatches.length >= 2) return true;
+  // Plausible domain-ish: a "." between alphanumerics AND at least one slash
+  const hasDomainDot = /[A-Za-z0-9]\.[A-Za-z0-9]/.test(text);
+  const hasSlash = /[\\/]/.test(text);
+  if (hasDomainDot && hasSlash) return true;
+  return false;
+}
+
+// Delimiter set: / \ - _ . : ? # & =
+// Capture in split so the delimiter is preserved at odd indices.
+const DELIM_SPLIT = /([/\\\-_.:?#&=])/;
+
+const HTML_ESCAPE_MAP: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+function htmlEscape(s: string): string {
+  return s.replace(/[&<>"']/g, (ch) => HTML_ESCAPE_MAP[ch]!);
+}
+
+/**
+ * If `text` is path-like, return a Preact fragment with <wbr/> inserted
+ * after each delimiter (/, \, -, _, ., :, ?, #, &, =). Otherwise return
+ * the input string unchanged so callers can trust non-path prose passes
+ * through untouched.
+ */
+export function smartBreak(text: string): VNode | string {
+  if (!isPathLike(text)) return text;
+  const parts = text.split(DELIM_SPLIT);
+  const nodes: (string | VNode)[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    nodes.push(part);
+    // Captured delimiter groups always land at odd indices.
+    if (i % 2 === 1) nodes.push(<wbr key={`wbr-${i}`} />);
+  }
+  return <>{nodes}</>;
+}
+
+/**
+ * Preact function component wrapper — pure, server-renderable.
+ * Stringifies children and defers to smartBreak.
+ *
+ * Return type is `any` so the component can be mounted from both
+ * Preact-typed and React-typed .tsx files (preact/compat makes this safe
+ * at runtime, but TypeScript treats Preact's VNode and React's JSX.Element
+ * as distinct types).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function SmartBreak({ children }: { children?: unknown }): any {
+  return <>{smartBreak(String(children ?? ""))}</>;
+}
+
+/**
+ * HTML-escape `text` and inject a literal "<wbr>" tag after every
+ * delimiter character. Unlike smartBreakToHtml, this does NOT check
+ * isPathLike — it unconditionally breaks on delimiters.
+ *
+ * Useful when a caller has already decided that a larger string is
+ * path-like and wants to apply the same wbr-injection rule to a
+ * substring (e.g. a segment produced by splitting on a search-query
+ * regex) without re-running the heuristic on fragments that are too
+ * short to be classified correctly on their own.
+ *
+ * Byte-identical to smartBreakToHtml for inputs where isPathLike is
+ * true, so the shared contract holds.
+ */
+export function escapeAndInjectWbr(text: string): string {
+  const parts = text.split(DELIM_SPLIT);
+  let out = "";
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    out += htmlEscape(part);
+    if (i % 2 === 1) out += "<wbr>";
+  }
+  return out;
+}
+
+/**
+ * HTML-string counterpart of smartBreak. Produces a safe HTML string
+ * with literal "<wbr>" tags injected after each delimiter in path-like
+ * input, and HTML-escaped text elsewhere. For non-path input, returns
+ * the HTML-escaped text unchanged (no wbr injection).
+ *
+ * Use this when the consumer cannot render Preact VNodes (e.g. building
+ * an HTML string for `set:html` / dangerouslySetInnerHTML).
+ */
+export function smartBreakToHtml(text: string): string {
+  if (!isPathLike(text)) return htmlEscape(text);
+  return escapeAndInjectWbr(text);
+}

package/templates/base/src/utils/tags.ts

@@ -0,0 +1,126 @@
+import type { DocsEntry } from "@/types/docs-entry";
+import { settings } from "@/config/settings";
+import { tagVocabulary } from "@/config/tag-vocabulary";
+import type { TagVocabularyEntry } from "@/config/tag-vocabulary-types";
+
+export interface TagInfo {
+  tag: string;
+  count: number;
+  docs: { slug: string; title: string; description?: string }[];
+}
+
+export interface ResolvedTag {
+  /** Canonical id after alias/redirect rewrites. Equal to the raw input when unchanged. */
+  canonical: string;
+  /** True when the canonical id should be dropped from aggregation (deprecated without redirect). */
+  deprecated: boolean;
+  /** True when the raw input matched a vocabulary entry (as id or alias). */
+  known: boolean;
+}
+
+interface VocabularyIndex {
+  byId: Map<string, TagVocabularyEntry>;
+  byAlias: Map<string, TagVocabularyEntry>;
+}
+
+let cachedIndex: VocabularyIndex | null = null;
+function getIndex(): VocabularyIndex {
+  if (cachedIndex) return cachedIndex;
+  const byId = new Map<string, TagVocabularyEntry>();
+  const byAlias = new Map<string, TagVocabularyEntry>();
+  for (const entry of tagVocabulary) {
+    byId.set(entry.id, entry);
+    for (const alias of entry.aliases ?? []) byAlias.set(alias, entry);
+  }
+  cachedIndex = { byId, byAlias };
+  return cachedIndex;
+}
+
+function vocabularyActive(): boolean {
+  return Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
+}
+
+/**
+ * Resolve a raw tag string to its canonical form.
+ *
+ * When the vocabulary is inactive (`tagVocabulary: false` or
+ * `tagGovernance: "off"`), the raw value passes through unchanged with
+ * `known: false, deprecated: false`. Otherwise:
+ *
+ * - A direct id match returns that id.
+ * - An alias match returns the aliased entry's id.
+ * - `deprecated: { redirect: "<id>" }` rewrites to the redirect target.
+ * - `deprecated: true` (no redirect) returns `deprecated: true` so callers
+ *   can drop the tag from aggregation.
+ * - An unknown value returns the raw string with `known: false`.
+ */
+export function resolveTag(raw: string): ResolvedTag {
+  if (!vocabularyActive()) {
+    return { canonical: raw, deprecated: false, known: false };
+  }
+  const { byId, byAlias } = getIndex();
+  const entry = byId.get(raw) ?? byAlias.get(raw);
+  if (!entry) return { canonical: raw, deprecated: false, known: false };
+  const dep = entry.deprecated;
+  if (dep && typeof dep === "object" && dep.redirect) {
+    const target = byId.get(dep.redirect);
+    if (target) return { canonical: target.id, deprecated: false, known: true };
+    // Redirect points at a missing id — treat like plain deprecation.
+    return { canonical: entry.id, deprecated: true, known: true };
+  }
+  if (dep === true) {
+    return { canonical: entry.id, deprecated: true, known: true };
+  }
+  return { canonical: entry.id, deprecated: false, known: true };
+}
+
+/**
+ * Resolve a list of raw tag strings (e.g. from frontmatter) to canonical ids,
+ * dropping deprecated-without-redirect entries and preserving order. Duplicates
+ * produced by alias collapse are removed.
+ */
+export function resolvePageTags(rawTags: readonly string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of rawTags) {
+    const { canonical, deprecated } = resolveTag(raw);
+    if (deprecated) continue;
+    if (seen.has(canonical)) continue;
+    seen.add(canonical);
+    out.push(canonical);
+  }
+  return out;
+}
+
+export function collectTags(
+  entries: DocsEntry[],
+  slugFn: (id: string, data: { slug?: string }) => string,
+): Map<string, TagInfo> {
+  const tagMap = new Map<string, TagInfo>();
+
+  for (const entry of entries) {
+    const rawTags = entry.data.tags ?? [];
+    const slug = slugFn(entry.id, entry.data);
+
+    const seen = new Set<string>();
+    for (const raw of rawTags) {
+      const resolved = resolveTag(raw);
+      if (resolved.deprecated) continue;
+      if (seen.has(resolved.canonical)) continue;
+      seen.add(resolved.canonical);
+
+      if (!tagMap.has(resolved.canonical)) {
+        tagMap.set(resolved.canonical, { tag: resolved.canonical, count: 0, docs: [] });
+      }
+      const info = tagMap.get(resolved.canonical)!;
+      info.count++;
+      info.docs.push({
+        slug,
+        title: entry.data.title,
+        description: entry.data.description,
+      });
+    }
+  }
+
+  return tagMap;
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowJs": true,
+    "jsx": "preserve",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+    "alwaysStrict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "#doc-history-meta": [".zfb/doc-history-meta.json"],
+      "react": ["./node_modules/preact/compat/"],
+      "react/jsx-runtime": ["./node_modules/preact/jsx-runtime"],
+      "react-dom": ["./node_modules/preact/compat/"]
+    }
+  },
+  "exclude": ["dist", "e2e/fixtures", "packages", "pages", "worktrees", "vendor", "src/**/__tests__", "vitest.config.ts"]
+}

package/templates/features/bodyFootUtil/files/src/utils/github.ts

@@ -0,0 +1,19 @@
+import { settings } from "@/config/settings";
+
+function trimTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+export function buildGitHubRepoUrl(): string | null {
+  if (!settings.githubUrl) return null;
+  return trimTrailingSlash(settings.githubUrl as string);
+}
+
+export function buildGitHubSourceUrl(
+  contentDir: string,
+  entryId: string,
+): string | null {
+  const repoUrl = buildGitHubRepoUrl();
+  if (!repoUrl) return null;
+  return `${repoUrl}/blob/HEAD/${contentDir}/${entryId}`;
+}