create-zudo-doc 0.1.0

package/dist/zfb-config-gen.js

@@ -0,0 +1,222 @@
+/**
+ * Programmatically generate zfb.config.ts from user choices.
+ *
+ * W7A (#1736): emits zfb plugins in the host's INLINE-OBJECT shape —
+ * `{ name: "./plugins/<plugin>.mjs", options: {...} }` — not the
+ * pre-cutover factory-import pattern (`import { fooPlugin } from
+ * "./src/integrations/foo"`). Inline functions are not supported by zfb's
+ * plugin runtime (see `@takazudo/zfb/plugins` source); plugins MUST be
+ * authored as standalone `.mjs` modules referenced from `zfb.config.ts`
+ * by `name`. The plugin source files are shipped by the base/feature
+ * templates under `plugins/<plugin>.mjs` and `templates/features/<feature>/
+ * files/plugins/<plugin>.mjs`.
+ *
+ * Replaces the former astro-config-gen.ts + content-config-gen.ts pair.
+ * In the zfb world, content-collection schemas live inside zfb.config.ts
+ * itself — there is no separate content.config.ts.
+ */
+export function generateZfbConfig(choices) {
+    const hasDocHistory = choices.features.includes("docHistory");
+    const hasLlmsTxt = choices.features.includes("llmsTxt");
+    const hasClaudeResources = choices.features.includes("claudeResources");
+    const hasTagGovernance = choices.features.includes("tagGovernance");
+    const lines = [];
+    // --- Imports ---
+    lines.push(`import { z } from "zod";`);
+    lines.push(`import { defineConfig } from "zfb/config";`);
+    lines.push(`import { settings } from "./src/config/settings";`);
+    if (hasTagGovernance) {
+        lines.push(`import { tagVocabulary } from "./src/config/tag-vocabulary";`);
+    }
+    lines.push(``);
+    // --- Tags schema builder (only when tagGovernance is selected) ---
+    if (hasTagGovernance) {
+        lines.push(`function buildTagsSchema() {`);
+        lines.push(`  const vocabularyActive = settings.tagVocabulary && settings.tagGovernance === "strict";`);
+        lines.push(`  if (!vocabularyActive) return z.array(z.string()).optional();`);
+        lines.push(`  const allowed = new Set<string>();`);
+        lines.push(`  for (const entry of tagVocabulary) {`);
+        lines.push(`    allowed.add(entry.id);`);
+        lines.push(`    for (const alias of entry.aliases ?? []) allowed.add(alias);`);
+        lines.push(`  }`);
+        lines.push(`  const allowedList = [...allowed];`);
+        lines.push(`  if (allowedList.length === 0) return z.array(z.string()).optional();`);
+        lines.push(`  const [first, ...rest] = allowedList;`);
+        lines.push(`  return z.array(z.enum([first, ...rest] as [string, ...string[]])).optional();`);
+        lines.push(`}`);
+        lines.push(``);
+    }
+    // --- Schema definition ---
+    lines.push(`const docsSchema = z`);
+    lines.push(`  .object({`);
+    lines.push(`    title: z.string(),`);
+    lines.push(`    description: z.string().optional(),`);
+    lines.push(`    category: z.string().optional(),`);
+    lines.push(`    sidebar_position: z.number().optional(),`);
+    lines.push(`    sidebar_label: z.string().optional(),`);
+    if (hasTagGovernance) {
+        lines.push(`    tags: buildTagsSchema(),`);
+    }
+    else {
+        lines.push(`    tags: z.array(z.string()).optional(),`);
+    }
+    lines.push(`    search_exclude: z.boolean().optional(),`);
+    lines.push(`    pagination_next: z.string().nullable().optional(),`);
+    lines.push(`    pagination_prev: z.string().nullable().optional(),`);
+    lines.push(`    draft: z.boolean().optional(),`);
+    lines.push(`    unlisted: z.boolean().optional(),`);
+    lines.push(`    hide_sidebar: z.boolean().optional(),`);
+    lines.push(`    hide_toc: z.boolean().optional(),`);
+    lines.push(`    doc_history: z.boolean().optional(),`);
+    lines.push(`    standalone: z.boolean().optional(),`);
+    lines.push(`    slug: z.string().optional(),`);
+    lines.push(`    generated: z.boolean().optional(),`);
+    lines.push(`  })`);
+    lines.push(`  .passthrough();`);
+    lines.push(``);
+    lines.push(`const docsSchemaJson = z.toJSONSchema(docsSchema) as Record<string, unknown>;`);
+    lines.push(``);
+    // --- Collection type ---
+    lines.push(`interface CollectionEntryShape {`);
+    lines.push(`  name: string;`);
+    lines.push(`  path: string;`);
+    lines.push(`  schema: Record<string, unknown>;`);
+    lines.push(`}`);
+    lines.push(``);
+    // --- Collections array ---
+    lines.push(`const collections: CollectionEntryShape[] = [];`);
+    lines.push(``);
+    lines.push(`collections.push({ name: "docs", path: settings.docsDir, schema: docsSchemaJson });`);
+    lines.push(``);
+    // Locale collections — empty loop when locales is {} (i18n disabled).
+    lines.push(`for (const [code, config] of Object.entries(settings.locales)) {`);
+    lines.push(`  collections.push({ name: \`docs-\${code}\`, path: config.dir, schema: docsSchemaJson });`);
+    lines.push(`}`);
+    lines.push(``);
+    // Version collections — outer `if` short-circuits when versions is false.
+    lines.push(`if (settings.versions) {`);
+    lines.push(`  for (const version of settings.versions) {`);
+    lines.push(`    collections.push({`);
+    lines.push(`      name: \`docs-v-\${version.slug}\`,`);
+    lines.push(`      path: version.docsDir,`);
+    lines.push(`      schema: docsSchemaJson,`);
+    lines.push(`    });`);
+    lines.push(`    if (version.locales) {`);
+    lines.push(`      for (const [code, config] of Object.entries(version.locales)) {`);
+    lines.push(`        collections.push({`);
+    lines.push(`          name: \`docs-v-\${version.slug}-\${code}\`,`);
+    lines.push(`          path: config.dir,`);
+    lines.push(`          schema: docsSchemaJson,`);
+    lines.push(`        });`);
+    lines.push(`      }`);
+    lines.push(`    }`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    lines.push(``);
+    // --- Locale helpers used by integrationPlugins (always emitted because
+    //     search-index + copy-public are always-on; locale-shaped data is
+    //     consumed by search-index even when there's only the default locale).
+    lines.push(`const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({`);
+    lines.push(`  code,`);
+    lines.push(`  dir: locale.dir,`);
+    lines.push(`}));`);
+    lines.push(`const localeRecord = Object.fromEntries(`);
+    lines.push(`  Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }]),`);
+    lines.push(`);`);
+    lines.push(``);
+    // --- Plugins — inline-object shape matches host. Each entry's `name`
+    //     is a relative path to a `.mjs` plugin module shipped by the
+    //     base/feature templates. zfb's plugin runtime resolves the module
+    //     and dispatches lifecycle hooks (preBuild / postBuild / devMiddleware)
+    //     on its default export. ---
+    lines.push(`const integrationPlugins = [`);
+    if (hasClaudeResources) {
+        lines.push(`  ...(settings.claudeResources`);
+        lines.push(`    ? [`);
+        lines.push(`        {`);
+        lines.push(`          name: "./plugins/claude-resources-plugin.mjs",`);
+        lines.push(`          options: {`);
+        lines.push(`            claudeDir: settings.claudeResources.claudeDir,`);
+        lines.push(`            projectRoot: settings.claudeResources.projectRoot,`);
+        lines.push(`            docsDir: settings.docsDir,`);
+        lines.push(`          },`);
+        lines.push(`        },`);
+        lines.push(`      ]`);
+        lines.push(`    : []),`);
+    }
+    if (hasDocHistory) {
+        lines.push(`  ...(settings.docHistory`);
+        lines.push(`    ? [`);
+        lines.push(`        {`);
+        lines.push(`          name: "./plugins/doc-history-plugin.mjs",`);
+        lines.push(`          options: {`);
+        lines.push(`            docsDir: settings.docsDir,`);
+        lines.push(`            locales: localeRecord,`);
+        lines.push(`          },`);
+        lines.push(`        },`);
+        lines.push(`      ]`);
+        lines.push(`    : []),`);
+    }
+    // search-index is always-on (matches host) — emits dist/search-index.json
+    // even when no <Search /> widget mounts; ~few-KB cost is acceptable and
+    // keeps the dev-middleware route registered for the always-mounted
+    // search widget in pages/lib/_header-with-defaults.tsx.
+    lines.push(`  {`);
+    lines.push(`    name: "./plugins/search-index-plugin.mjs",`);
+    lines.push(`    options: {`);
+    lines.push(`      docsDir: settings.docsDir,`);
+    lines.push(`      locales: localeRecord,`);
+    lines.push(`      base: settings.base,`);
+    lines.push(`    },`);
+    lines.push(`  },`);
+    if (hasLlmsTxt) {
+        lines.push(`  ...(settings.llmsTxt`);
+        lines.push(`    ? [`);
+        lines.push(`        {`);
+        lines.push(`          name: "./plugins/llms-txt-plugin.mjs",`);
+        lines.push(`          options: {`);
+        lines.push(`            siteName: settings.siteName,`);
+        lines.push(`            siteDescription: settings.siteDescription,`);
+        lines.push(`            base: settings.base,`);
+        lines.push(`            siteUrl: settings.siteUrl,`);
+        lines.push(`            defaultLocaleDir: settings.docsDir,`);
+        lines.push(`            locales: localeArray,`);
+        lines.push(`          },`);
+        lines.push(`        },`);
+        lines.push(`      ]`);
+        lines.push(`    : []),`);
+    }
+    // copy-public is always-on (matches host) — workaround for upstream zfb
+    // gap where `zfb build` does not copy `public/` to dist/. Empty/missing
+    // public/ is a no-op, so the cost to projects without public/ is zero.
+    lines.push(`  {`);
+    lines.push(`    name: "./plugins/copy-public-plugin.mjs",`);
+    lines.push(`    options: {`);
+    lines.push(`      publicDir: "public",`);
+    lines.push(`    },`);
+    lines.push(`  },`);
+    lines.push(`];`);
+    lines.push(``);
+    // --- Export ---
+    lines.push(`export default defineConfig({`);
+    lines.push(`  framework: "preact",`);
+    lines.push(`  tailwind: { enabled: true },`);
+    lines.push(`  collections,`);
+    lines.push(`  stripMdExt: true,`);
+    lines.push(`  resolveMarkdownLinks: {`);
+    lines.push(`    enabled: true,`);
+    lines.push(`    dirs: [`);
+    lines.push(`      { dir: settings.docsDir, routePrefix: "/docs/" },`);
+    lines.push(`      ...Object.entries(settings.locales).map(([code, locale]) => ({`);
+    lines.push(`        dir: locale.dir,`);
+    lines.push(`        routePrefix: \`/\${code}/docs/\`,`);
+    lines.push(`      })),`);
+    lines.push(`    ],`);
+    lines.push(`    onBrokenLinks: "warn",`);
+    lines.push(`  },`);
+    lines.push(`  base: settings.base,`);
+    lines.push(`  trailingSlash: settings.trailingSlash,`);
+    lines.push(`  plugins: integrationPlugins,`);
+    lines.push(`});`);
+    return lines.join("\n") + "\n";
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "create-zudo-doc",
+  "version": "0.1.0",
+  "description": "Create a new zudo-doc documentation site",
+  "license": "MIT",
+  "author": "Takeshi Takatsudo",
+  "homepage": "https://zudo-doc.takazudomodular.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zudolab/zudo-doc.git",
+    "directory": "packages/create-zudo-doc"
+  },
+  "bugs": {
+    "url": "https://github.com/zudolab/zudo-doc/issues"
+  },
+  "keywords": [
+    "documentation",
+    "zfb",
+    "mdx",
+    "scaffold",
+    "create",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "bin": {
+    "create-zudo-doc": "./bin/create-zudo-doc.js"
+  },
+  "main": "./dist/api.js",
+  "exports": {
+    ".": "./dist/api.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "!dist/__tests__"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:slow": "vitest run --config vitest.slow.config.ts",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "fs-extra": "^11.3.0",
+    "minimist": "^1.2.8",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}

package/templates/base/.htmlvalidate.json

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "element-permitted-content": "error"
+  }
+}

package/templates/base/.zfb/doc-history-meta.json

@@ -0,0 +1 @@
+{}

package/templates/base/pages/404.tsx

@@ -0,0 +1,55 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/404.astro → zfb page module.
+//
+// The 404 page is a static route with no dynamic params. zfb emits it as
+// dist/404.html so the host platform (Cloudflare Pages, Netlify, etc.) can
+// serve it for unmatched requests. No paths() export needed.
+//
+// The original Astro page rendered the full html/head/body inline without
+// DocLayout because the 404 page intentionally has no sidebar/TOC/header.
+// This port wraps via DocLayoutWithDefaults with hideSidebar/hideToc plus
+// a noindex meta so search engines do not index it.
+
+import { defaultLocale } from "@/config/i18n";
+import { settings } from "@/config/settings";
+import { withBase } from "@/utils/base";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+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 { BodyEndIslands } from "./lib/_body-end-islands";
+
+export const frontmatter = { title: "404" };
+
+export default function NotFoundPage(): JSX.Element {
+  const locale = defaultLocale;
+  const title = "Page Not Found";
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(title)}
+      head={<HeadWithDefaults title={title} />}
+      lang={locale}
+      noindex={true}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <div class="min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl">
+        <h1 class="text-display font-bold mb-vsp-md">404</h1>
+        <p class="text-title text-muted mb-vsp-xl">Page not found.</p>
+        <a
+          href={withBase("/")}
+          class="bg-accent px-hsp-lg py-vsp-xs font-medium text-bg hover:bg-accent-hover"
+        >
+          Back to Home
+        </a>
+      </div>
+    </DocLayoutWithDefaults>
+  );
+}

package/templates/base/pages/_data.ts

@@ -0,0 +1,179 @@
+// pages/_data.ts — zfb-compatible data helpers for doc page modules.
+//
+// Provides the bridge between zfb's CollectionEntry (from "zfb/content") and
+// the utility functions in @/utils/docs that expect DocsEntry (which carries
+// an `id` field mirroring Astro's collection entry id).
+//
+// Sync convention (ADR-004):
+//   getCollection() resolves from the pre-loaded ContentSnapshot without an
+//   async boundary. paths() exports call getDocs() without await. The Promise
+//   wrapper on the type is a v0 artefact — the synchronous snapshot path is
+//   the production contract.
+
+import { getCollection } from "zfb/content";
+import type { CollectionEntry } from "zfb/content";
+import type { DocsEntry } from "@/types/docs-entry";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Frontmatter shape shared by all docs collections (EN, locale, versioned).
+ * Matches the zod schema in zfb.config.ts field-for-field.
+ * `.passthrough()` equivalent: the index signature [key: string]: unknown
+ * keeps custom frontmatter keys available (e.g. for frontmatter-preview).
+ */
+export type ZfbDocsData = {
+  title: string;
+  description?: string;
+  category?: string;
+  sidebar_position?: number;
+  sidebar_label?: string;
+  tags?: string[];
+  search_exclude?: boolean;
+  pagination_next?: string | null;
+  pagination_prev?: string | null;
+  draft?: boolean;
+  unlisted?: boolean;
+  hide_sidebar?: boolean;
+  hide_toc?: boolean;
+  doc_history?: boolean;
+  standalone?: boolean;
+  slug?: string;
+  generated?: boolean;
+  [key: string]: unknown;
+};
+
+/**
+ * zfb collection entry augmented with the `id` and `collection` fields that
+ * @/utils/docs utility functions (buildNavTree, buildBreadcrumbs, …) expect
+ * from DocsEntry.
+ *
+ * `id` is bridged from `slug` — in Astro, `id` was the file-path identifier
+ * (e.g. "getting-started/intro"); in zfb, the same role is played by `slug`.
+ * Mapping them keeps the utility functions working without modification.
+ */
+export type ZfbDocsEntry = CollectionEntry<ZfbDocsData> & {
+  /** Bridged from `slug` for @/utils/docs compat. */
+  id: string;
+  /** Collection name, e.g. "docs", "docs-ja", "docs-v-1.0". */
+  collection: string;
+};
+
+// ---------------------------------------------------------------------------
+// Loaders
+// ---------------------------------------------------------------------------
+
+/**
+ * Load docs from a named collection synchronously (ADR-004 sync contract).
+ *
+ * `getCollection` resolves from the ContentSnapshot when called inside a
+ * paths() evaluation. The `as unknown as` cast converts the nominal Promise
+ * wrapper to a plain array — safe because the snapshot path is synchronous.
+ *
+ * The returned entries include:
+ *   - All CollectionEntry fields (slug, data, body, module_specifier, Content)
+ *   - `id` — same value as `slug`, for @/utils/docs compat
+ *   - `collection` — the collection name, for DocsEntry compat
+ */
+export function getDocs(collectionName: string): ZfbDocsEntry[] {
+  const entries = getCollection(collectionName) as unknown as CollectionEntry<ZfbDocsData>[];
+  return entries.map((e) => ({
+    ...e,
+    // Astro-compat: strip a trailing `/index` from the entry id so
+    // `getting-started/index.mdx` → id "getting-started" (matching
+    // Astro 5's `glob()` collection loader). Downstream nav helpers
+    // (`buildNavTree`, `buildBreadcrumbs`, …) keyed off the stripped
+    // form long before zfb existed; emitting the unstripped slug here
+    // produces ambiguous-URL collisions at paths()-expansion time.
+    id: stripIndexSuffix(e.slug),
+    collection: collectionName,
+  }));
+}
+
+function stripIndexSuffix(slug: string): string {
+  if (slug === "index") return "";
+  return slug.endsWith("/index") ? slug.slice(0, -"/index".length) : slug;
+}
+
+/**
+ * Augment a raw zfb collection result with the Astro-style
+ * `id`/`collection` fields that downstream `@/utils/docs` helpers
+ * (and the `DocPageEntry` extender shape used by `[...slug].tsx`
+ * pages) expect. Use this when a page needs a typed array more
+ * specific than `DocsEntry` — pages that only need `DocsEntry[]`
+ * can use [`loadDocs`] / [`getDocs`] directly.
+ */
+export function bridgeEntries<T = ZfbDocsData>(
+  entries: ReadonlyArray<CollectionEntry<T>>,
+  collectionName: string,
+): Array<CollectionEntry<T> & { id: string; collection: string }> {
+  return entries.map((e) => ({
+    ...e,
+    id: stripIndexSuffix(e.slug),
+    collection: collectionName,
+  }));
+}
+
+/**
+ * Cast ZfbDocsEntry[] to DocsEntry[] for passing to @/utils/docs utilities.
+ *
+ * The types are structurally compatible: ZfbDocsEntry has every required field
+ * of DocsEntry (id, collection, data, body). The optional `rendered` and
+ * `filePath` fields of DocsEntry are absent but not required.
+ */
+export function asDocsEntries(entries: ZfbDocsEntry[]): DocsEntry[] {
+  return entries as unknown as DocsEntry[];
+}
+
+/**
+ * One-shot helper for paths()/render-time pages that just need a
+ * `DocsEntry[]` for `@/utils/docs` consumption — wraps `getDocs` and
+ * the `asDocsEntries` cast so call sites stay one-line. Use this from
+ * any page that previously did
+ * `getCollection("docs") as unknown as DocsEntry[]` — that idiom
+ * silently dropped the `id`/`collection` fields the utility helpers
+ * read, which threw `Cannot read properties of undefined` at runtime.
+ */
+export function loadDocs(collectionName: string): DocsEntry[] {
+  return asDocsEntries(getDocs(collectionName));
+}
+
+/**
+ * Filter out draft entries.
+ * Drafts are always excluded in static-build paths() context.
+ */
+export function filterDrafts(entries: ZfbDocsEntry[]): ZfbDocsEntry[] {
+  return entries.filter((e) => !e.data.draft);
+}
+
+/**
+ * Merge locale docs with base (EN) fallbacks.
+ *
+ * Strategy (mirrors src/utils/locale-docs.ts):
+ *   1. Load locale docs (e.g. "docs-ja")
+ *   2. Load base docs ("docs")
+ *   3. Locale docs take priority; base docs fill in missing slugs.
+ *   4. Track which slugs came from base (fallbackSlugs).
+ *
+ * Returns { allDocs, fallbackSlugs }.
+ * categoryMeta is not merged here — callers use loadCategoryMeta() directly.
+ */
+export function mergeLocaleDocs(
+  locale: string,
+): { allDocs: ZfbDocsEntry[]; fallbackSlugs: Set<string> } {
+  const localeDocs = filterDrafts(getDocs(`docs-${locale}`));
+  const baseDocs = filterDrafts(getDocs("docs"));
+
+  const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? d.id));
+
+  const fallbackDocs = baseDocs.filter(
+    (d) => !localeSlugSet.has(d.data.slug ?? d.id),
+  );
+
+  return {
+    allDocs: [...localeDocs, ...fallbackDocs],
+    fallbackSlugs: new Set(fallbackDocs.map((d) => d.data.slug ?? d.id)),
+  };
+}