create-zudo-doc 0.1.0

package/templates/features/docHistory/files/src/utils/doc-history.ts

@@ -0,0 +1,180 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import type { DocHistoryEntry, DocHistoryData } from "@/types/doc-history";
+import { collectMdFiles } from "./content-files";
+
+/** Shared options to suppress git stderr noise */
+const QUIET: { encoding: "utf-8"; stdio: ["pipe", "pipe", "pipe"] } = {
+  encoding: "utf-8",
+  stdio: ["pipe", "pipe", "pipe"],
+};
+
+/** Cache the repo root to avoid repeated git calls */
+let repoRootCache: string | null = null;
+
+function getRepoRoot(): string {
+  if (repoRootCache) return repoRootCache;
+  repoRootCache = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf-8",
+  }).trim();
+  return repoRootCache;
+}
+
+/** Convert an absolute path to a repo-relative path for git commands */
+function toRepoRelative(absolutePath: string): string {
+  return path.relative(getRepoRoot(), absolutePath);
+}
+
+/**
+ * Get the list of commit hashes that touched a file, newest first.
+ * Uses --follow to track renames.
+ * Limits to maxEntries commits (default 50).
+ */
+export function getFileCommits(
+  filePath: string,
+  maxEntries = 50,
+): string[] {
+  try {
+    const output = execFileSync(
+      "git",
+      [
+        "log",
+        "--follow",
+        "--format=%H",
+        "-n",
+        String(maxEntries),
+        "--",
+        filePath,
+      ],
+      QUIET,
+    ).trim();
+    return output ? [...new Set(output.split("\n"))] : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get metadata for a specific commit on a file.
+ * Returns { hash, date, author, message } with full hash for unique identification.
+ */
+export function getCommitInfo(
+  hash: string,
+  filePath: string,
+): Omit<DocHistoryEntry, "content"> {
+  try {
+    const output = execFileSync(
+      "git",
+      ["log", "-1", "--format=%H%n%aI%n%aN%n%s", hash, "--", filePath],
+      QUIET,
+    ).trim();
+    const lines = output.split("\n");
+    return {
+      hash: lines[0] ?? hash,
+      date: lines[1] ?? "",
+      author: lines[2] ?? "",
+      message: lines[3] ?? "",
+    };
+  } catch {
+    return { hash, date: "", author: "", message: "" };
+  }
+}
+
+/**
+ * Get the file content at a specific commit.
+ * Accepts absolute paths and converts to repo-relative for git show.
+ * Handles renamed files by falling back to the old path via git log --follow.
+ */
+export function getFileAtCommit(hash: string, filePath: string): string {
+  const relPath = path.isAbsolute(filePath)
+    ? toRepoRelative(filePath)
+    : filePath;
+
+  try {
+    return execFileSync("git", ["show", `${hash}:${relPath}`], QUIET);
+  } catch {
+    // File may have been renamed — find the old path at this commit
+    try {
+      const oldPath = execFileSync(
+        "git",
+        [
+          "log",
+          "-1",
+          "--follow",
+          "--diff-filter=R",
+          "--format=",
+          "--name-only",
+          hash,
+          "--",
+          relPath,
+        ],
+        QUIET,
+      ).trim();
+      if (oldPath) {
+        return execFileSync("git", ["show", `${hash}:${oldPath}`], QUIET);
+      }
+    } catch {
+      // ignore
+    }
+
+    // Last resort: use git log --follow to find the path at this revision
+    try {
+      const followOutput = execFileSync(
+        "git",
+        [
+          "log",
+          "--follow",
+          "--format=%H",
+          "--name-only",
+          "--diff-filter=AMRC",
+          "--",
+          relPath,
+        ],
+        QUIET,
+      ).trim();
+      const lines = followOutput.split("\n").filter(Boolean);
+      // Lines alternate: hash, filename, hash, filename...
+      for (let i = 0; i < lines.length - 1; i += 2) {
+        if (lines[i] === hash && lines[i + 1]) {
+          return execFileSync(
+            "git",
+            ["show", `${hash}:${lines[i + 1]}`],
+            QUIET,
+          );
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    return "";
+  }
+}
+
+/**
+ * Get the complete history for a document file.
+ * Returns DocHistoryData with all entries populated.
+ */
+export function getDocHistory(
+  filePath: string,
+  slug: string,
+  maxEntries = 50,
+): DocHistoryData {
+  const commits = getFileCommits(filePath, maxEntries);
+  const entries: DocHistoryEntry[] = commits.map((hash) => {
+    const info = getCommitInfo(hash, filePath);
+    const content = getFileAtCommit(hash, filePath);
+    return { ...info, content };
+  });
+  return { slug, filePath, entries };
+}
+
+/**
+ * Collect all MDX/md files in a content directory.
+ * Delegates to the shared collectMdFiles utility from content-files.ts.
+ */
+export function collectContentFiles(
+  contentDir: string,
+): Array<{ filePath: string; slug: string }> {
+  return collectMdFiles(contentDir);
+}

package/templates/features/docTags/files/pages/[locale]/docs/tags/[tag].tsx

@@ -0,0 +1,116 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/[locale]/docs/tags/[tag].astro → zfb page module.
+//
+// Non-default-locale per-tag detail page. paths() enumerates every
+// (locale, tag) combination across all non-default locales defined in
+// settings.locales, using the same locale-first + base-fallback merge
+// strategy as the Astro original.
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { locale: string; tag: string }
+//   props:  { tagInfo: TagInfo }
+//
+// Fallback strategy: see pages/lib/locale-merge.ts for full details.
+//   Locale docs take priority; base docs fill in missing slugs.
+//   Build tag map; emit one route per (locale, tag) pair.
+
+import { mergeLocaleDocs } from "../../../lib/locale-merge";
+import { collectTags } from "@/utils/tags";
+import type { TagInfo } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { t } from "@/config/i18n";
+import { withBase, docsUrl } from "@/utils/base";
+import { settings } from "@/config/settings";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
+import { DocCardGrid } from "@takazudo/zudo-doc/nav-indexing";
+import type { JSX } from "preact";
+import { FooterWithDefaults } from "../../../lib/_footer-with-defaults";
+import { HeaderWithDefaults } from "../../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../../lib/_head-with-defaults";
+import { composeMetaTitle } from "../../../lib/_compose-meta-title";
+import { DocHistoryArea } from "../../../lib/_doc-history-area";
+import { BodyEndIslands } from "../../../lib/_body-end-islands";
+
+export const frontmatter = { title: "Tag" };
+
+/** One route per (non-default locale, tag) pair. */
+export function paths(): Array<{
+  params: { locale: string; tag: string };
+  props: { tagInfo: TagInfo };
+}> {
+  const result: Array<{
+    params: { locale: string; tag: string };
+    props: { tagInfo: TagInfo };
+  }> = [];
+
+  for (const locale of Object.keys(settings.locales)) {
+    const docs = mergeLocaleDocs(locale);
+    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+
+    for (const [tag, tagInfo] of tagMap.entries()) {
+      result.push({
+        params: { locale, tag },
+        props: { tagInfo },
+      });
+    }
+  }
+
+  return result;
+}
+
+interface PageProps {
+  params: { locale: string; tag: string };
+  tagInfo: TagInfo;
+}
+
+export default function LocaleDocTagPage({
+  params,
+  tagInfo,
+}: PageProps): JSX.Element {
+  const { locale, tag } = params;
+
+  const countText =
+    tagInfo.count === 1
+      ? t("doc.pageCountSingle", locale).replace("{count}", String(tagInfo.count))
+      : t("doc.pageCount", locale).replace("{count}", String(tagInfo.count));
+
+  const pageTitle = `${t("doc.taggedWith", locale)}: ${tag}`;
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    {
+      label: t("doc.allTags", locale),
+      href: withBase(`/${locale}/docs/tags`),
+    },
+    { label: tag },
+  ];
+
+  const cardItems = tagInfo.docs.map((doc) => ({
+    href: docsUrl(doc.slug, locale),
+    title: doc.title,
+    description: doc.description,
+  }));
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/docs/tags/${tag}`)} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-xs">{pageTitle}</h1>
+      <p class="text-muted mb-vsp-lg">{countText}</p>
+      <DocCardGrid ariaLabel={pageTitle} items={cardItems} />
+      <DocHistoryArea slug={`tags/${tag}`} locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}

package/templates/features/docTags/files/pages/[locale]/docs/tags/index.tsx

@@ -0,0 +1,99 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/[locale]/docs/tags/index.astro → zfb page module.
+//
+// Non-default-locale "All Tags" index page. paths() emits one route per
+// locale defined in settings.locales (English has no /en prefix — it is
+// handled by pages/docs/tags/index.tsx). The component recomputes the tag
+// map at render time using a locale-doc + base-doc fallback strategy that
+// mirrors src/components/tag-nav.astro's non-default-locale branch.
+//
+// Fallback strategy (locale first, base as fill): see pages/lib/locale-merge.ts
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { locale: string }
+//   props:  (none — tag map computed at render time)
+
+import { mergeLocaleDocs } from "../../../lib/locale-merge";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { t } from "@/config/i18n";
+import { withBase } from "@/utils/base";
+import { settings } from "@/config/settings";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
+import { TagNav } from "@takazudo/zudo-doc/nav-indexing";
+import type { TagItem, TagNavLabels } from "@takazudo/zudo-doc/nav-indexing";
+import type { JSX } from "preact";
+import { FooterWithDefaults } from "../../../lib/_footer-with-defaults";
+import { HeaderWithDefaults } from "../../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../../lib/_head-with-defaults";
+import { composeMetaTitle } from "../../../lib/_compose-meta-title";
+import { DocHistoryArea } from "../../../lib/_doc-history-area";
+import { BodyEndIslands } from "../../../lib/_body-end-islands";
+
+export const frontmatter = { title: "All Tags" };
+
+/** One route per non-default locale (prefixDefaultLocale: false). */
+export function paths(): Array<{ params: { locale: string } }> {
+  return Object.keys(settings.locales).map((locale) => ({
+    params: { locale },
+  }));
+}
+
+interface PageProps {
+  params: { locale: string };
+}
+
+export default function LocaleTagsIndexPage({
+  params,
+}: PageProps): JSX.Element {
+  const { locale } = params;
+  const pageTitle = t("doc.allTags", locale);
+
+  const docs = mergeLocaleDocs(locale);
+  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+
+  const labels: TagNavLabels = {
+    tags: t("doc.tags", locale),
+    taggedWith: t("doc.taggedWith", locale),
+  };
+
+  // Sort alphabetically using the page locale — mirrors tag-nav.astro sort.
+  const tags: TagItem[] = [...tagMap.values()]
+    .sort((a, b) => a.tag.localeCompare(b.tag, locale))
+    .map((info) => ({
+      tag: info.tag,
+      count: info.count,
+      href: withBase(`/${locale}/docs/tags/${info.tag}`),
+    }));
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    { label: pageTitle },
+  ];
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/docs/tags`)} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-lg">{pageTitle}</h1>
+      {!settings.docTags || tags.length === 0 ? (
+        <p class="text-muted">{t("doc.noTags", locale)}</p>
+      ) : (
+        <TagNav variant="all" tags={tags} labels={labels} />
+      )}
+      <DocHistoryArea slug="tags" locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}

package/templates/features/docTags/files/pages/docs/tags/[tag].tsx

@@ -0,0 +1,101 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/docs/tags/[tag].astro → zfb page module.
+//
+// Default-locale (en) per-tag detail page. paths() enumerates one route per
+// unique tag in the "docs" collection and passes the resolved TagInfo as a
+// prop so the component has zero extra collection reads at render time.
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { tag: string }
+//   props:  { tagInfo: TagInfo }
+//
+// Data flow:
+//   getCollection("docs") [sync] → collectTags() → one route per tag
+//   render: DocCardGrid with pre-resolved TagInfo.docs items
+
+import { getCollection } from "zfb/content";
+import { collectTags } from "@/utils/tags";
+import type { TagInfo } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { t, defaultLocale } from "@/config/i18n";
+import { settings } from "@/config/settings";
+import { withBase, docsUrl } from "@/utils/base";
+import type { DocsEntry } from "@/types/docs-entry";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
+import { DocCardGrid } from "@takazudo/zudo-doc/nav-indexing";
+import type { JSX } from "preact";
+import { bridgeEntries } from "../../_data";
+import { FooterWithDefaults } from "../../lib/_footer-with-defaults";
+import { HeaderWithDefaults } from "../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../lib/_head-with-defaults";
+import { composeMetaTitle } from "../../lib/_compose-meta-title";
+import { DocHistoryArea } from "../../lib/_doc-history-area";
+import { BodyEndIslands } from "../../lib/_body-end-islands";
+
+export const frontmatter = { title: "Tag" };
+
+/** One entry per unique tag in the default-locale collection. */
+export function paths(): Array<{
+  params: { tag: string };
+  props: { tagInfo: TagInfo };
+}> {
+  const allDocs = (bridgeEntries(getCollection("docs"), "docs") as unknown as DocsEntry[]);
+  const docs = allDocs.filter((doc) => !doc.data.unlisted && !doc.data.draft);
+  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+
+  return [...tagMap.entries()].map(([tag, tagInfo]) => ({
+    params: { tag },
+    props: { tagInfo },
+  }));
+}
+
+interface PageProps {
+  params: { tag: string };
+  tagInfo: TagInfo;
+}
+
+export default function DocTagPage({ params, tagInfo }: PageProps): JSX.Element {
+  const { tag } = params;
+  const locale = defaultLocale;
+
+  const countText =
+    tagInfo.count === 1
+      ? t("doc.pageCountSingle", locale).replace("{count}", String(tagInfo.count))
+      : t("doc.pageCount", locale).replace("{count}", String(tagInfo.count));
+
+  const pageTitle = `${t("doc.taggedWith", locale)}: ${tag}`;
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    { label: t("doc.allTags", locale), href: withBase("/docs/tags") },
+    { label: tag },
+  ];
+
+  const cardItems = tagInfo.docs.map((doc) => ({
+    href: docsUrl(doc.slug, locale),
+    title: doc.title,
+    description: doc.description,
+  }));
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/docs/tags/${tag}`)} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-xs">{pageTitle}</h1>
+      <p class="text-muted mb-vsp-lg">{countText}</p>
+      <DocCardGrid ariaLabel={pageTitle} items={cardItems} />
+      <DocHistoryArea slug={`tags/${tag}`} locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}

package/templates/features/docTags/files/pages/docs/tags/index.tsx

@@ -0,0 +1,86 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/docs/tags/index.astro → zfb page module.
+//
+// Default-locale (en) "All Tags" index page. Collects every tag across the
+// "docs" collection, sorts them alphabetically, and renders a full tag cloud
+// via the v2 TagNav component. No dynamic params — single static route.
+//
+// Data flow:
+//   getCollection("docs")   [sync, zfb/content]
+//   → collectTags()         builds { tag → { count, docs[] } }
+//   → sort by tag           preserves sort parity with Astro original
+//   → TagNav variant="all"  renders the chip cloud
+
+import { getCollection } from "zfb/content";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { t, defaultLocale } from "@/config/i18n";
+import { withBase } from "@/utils/base";
+import { settings } from "@/config/settings";
+import type { DocsEntry } from "@/types/docs-entry";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
+import { TagNav } from "@takazudo/zudo-doc/nav-indexing";
+import type { TagItem, TagNavLabels } from "@takazudo/zudo-doc/nav-indexing";
+import type { JSX } from "preact";
+import { bridgeEntries } from "../../_data";
+import { FooterWithDefaults } from "../../lib/_footer-with-defaults";
+import { HeaderWithDefaults } from "../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../lib/_head-with-defaults";
+import { composeMetaTitle } from "../../lib/_compose-meta-title";
+import { DocHistoryArea } from "../../lib/_doc-history-area";
+import { BodyEndIslands } from "../../lib/_body-end-islands";
+
+export const frontmatter = { title: "All Tags" };
+
+export default function DocsTagsIndexPage(): JSX.Element {
+  const locale = defaultLocale;
+  const pageTitle = t("doc.allTags", locale);
+
+  const allDocs = (bridgeEntries(getCollection("docs"), "docs") as unknown as DocsEntry[]);
+  const docs = allDocs.filter((doc) => !doc.data.unlisted && !doc.data.draft);
+  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+
+  const labels: TagNavLabels = {
+    tags: t("doc.tags", locale),
+    taggedWith: t("doc.taggedWith", locale),
+  };
+
+  // Sort alphabetically — mirrors the Astro tag-nav.astro sort order.
+  const tags: TagItem[] = [...tagMap.values()]
+    .sort((a, b) => a.tag.localeCompare(b.tag, locale))
+    .map((info) => ({
+      tag: info.tag,
+      count: info.count,
+      href: withBase(`/docs/tags/${info.tag}`),
+    }));
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    { label: pageTitle },
+  ];
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/docs/tags")} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-lg">{pageTitle}</h1>
+      {!settings.docTags || tags.length === 0 ? (
+        <p class="text-muted">{t("doc.noTags", locale)}</p>
+      ) : (
+        <TagNav variant="all" tags={tags} labels={labels} />
+      )}
+      <DocHistoryArea slug="tags" locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}