create-zudo-doc 3.1.0 → 3.3.0

package/dist/scaffold.js

@@ -1,28 +1,34 @@
 import fs from "fs-extra";
 import path from "path";
 import { fileURLToPath } from "url";
-import { generateSettingsFile } from "./settings-gen.js";
 import { generateZfbConfig } from "./zfb-config-gen.js";
 import { generateCLAUDEFile } from "./claude-md-gen.js";
 import { composeFeatures } from "./compose.js";
 import { featureModules } from "./features/index.js";
-import { capitalize, getSecondaryLang } from "./utils.js";
+import { capitalize, getSecondaryLang, pmRunCommand } from "./utils.js";
 export { getSecondaryLang };
 /**
- * Pinned `@takazudo/zudo-doc` version used in both `generatePackageJson()`
- * and the `.zudo-doc.json` seed written by `scaffold()`. Hoisted as a shared
- * constant so the dep pin and the provenance seed can never drift.
+ * Pinned `@takazudo/zudo-doc` version used by `generatePackageJson()`.
+ * Hoisted as a shared constant (kept even though it now has a single
+ * call site) because `scripts/check-pin-parity.mjs` resolves this exact
+ * declaration below via its constant-reference regex form (see that
+ * script's `readScaffoldPin()`) — keep the declaration line's shape
+ * parseable (const name, `=`, a quoted literal) and do NOT repeat that
+ * exact pattern anywhere earlier in this file (a comment containing the
+ * literal text would false-match the same regex, since it isn't anchored
+ * to a real `export const` statement).
  *
- * Strip the caret from this string to get the bare version for provenance:
- *   ZUDO_DOC_PIN.replace(/^\^/, "")   →  "1.0.0"
+ * `.zudo-doc.json` is NO LONGER seeded here (locked decision #2653 #6 —
+ * lazy-create on first `zudo-doc eject`; `packages/zudo-doc/src/eject/index.ts`
+ * already tolerates its absence and writes the file on first successful eject).
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^3.1.0";
+export const ZUDO_DOC_PIN = "^3.3.0";
 /**
- * Files in `templates/base/**` that must never be copied into a generated
- * project. Each entry is matched against the path relative to `templates/base/`
- * (POSIX-style, forward slashes).
+ * Files in `templates/base/**` that must not be copied by the unconditional
+ * base mirror. Each entry is matched against the path relative to
+ * `templates/base/` (POSIX-style, forward slashes).
  *
  * W2 spec-lock Decision 5 (#1728) — `pages/api/**` is worker-only SSR
  * (uses `@takazudo/zfb-adapter-cloudflare`, `prerender = false`) and is
@@ -32,6 +38,7 @@ export const ZUDO_DOC_PIN = "^3.1.0";
  */
 const EXCLUDE_FROM_MIRROR = [
     /^pages\/api(\/|$)/,
+    /^scripts\/setup-doc-skill\.sh$/,
 ];
 /**
  * `fs.copy` filter for the `templates/base/` → target-dir copy. Returns
@@ -106,7 +113,7 @@ sidebar_position: 2
 
 ## Requirements
 
-- Node.js 18 or later
+- Node.js 22 or later
 - pnpm (recommended), npm, yarn, or bun
 
 ## Create a New Project
@@ -134,7 +141,7 @@ sidebar_position: 2
 
 ## 動作要件
 
-- Node.js 18 以降
+- Node.js 22 以降
 - pnpm（推奨）、npm、yarn、または bun
 
 ## 新しいプロジェクトを作成する
@@ -201,7 +208,7 @@ export async function scaffold(choices) {
     const templatesDir = path.join(pkgRoot, "templates");
     const baseDir = path.join(templatesDir, "base");
     const featuresDir = path.join(templatesDir, "features");
-    // For skillSymlinker, we still need the monorepo root for the script
+    // Still needed for source-checkout-only assets such as Claude skills.
     const monorepoRoot = path.resolve(pkgRoot, "../..");
     await fs.ensureDir(targetDir);
     // 1. Copy base template
@@ -214,11 +221,9 @@ export async function scaffold(choices) {
     });
     // 2. Copy skill symlinker script when enabled
     if (choices.features.includes("skillSymlinker")) {
-        const scriptSrc = path.join(monorepoRoot, "scripts/setup-doc-skill.sh");
+        const scriptSrc = path.join(baseDir, "scripts/setup-doc-skill.sh");
         const scriptDest = path.join(targetDir, "scripts/setup-doc-skill.sh");
-        if (await fs.pathExists(scriptSrc)) {
-            await fs.copy(scriptSrc, scriptDest);
-        }
+        await fs.copy(scriptSrc, scriptDest);
     }
     // 2b. Copy user-facing Claude Code skills when enabled
     // Ships the curated zudo-doc-* skills (design-system, translate, version-bump)
@@ -284,21 +289,17 @@ export async function scaffold(choices) {
             await fs.outputFile(path.join(targetDir, `src/content/docs-${secondaryLang}/changelog/index.mdx`), secondaryChangelogContent);
         }
     }
-    // 3. Generate programmatic files
-    const settingsContent = generateSettingsFile(choices);
-    await fs.outputFile(path.join(targetDir, "src/config/settings.ts"), settingsContent);
+    // 3. Generate the one config file. There is no more src/config/settings.ts —
+    // every user choice rides straight into zudoDoc({...}) in zfb.config.ts
+    // (locked decision #2653 #2 — diff-from-defaults single config).
     const zfbConfigContent = generateZfbConfig(choices);
     await fs.outputFile(path.join(targetDir, "zfb.config.ts"), zfbConfigContent);
     const pkg = generatePackageJson(choices);
     await fs.outputFile(path.join(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
-    // Seed .zudo-doc.json — provenance marker for `zudo-doc eject <component>`.
-    // packageVersion is the bare version string (caret stripped from ZUDO_DOC_PIN)
-    // so it records the concrete version the scaffold targets; the eject CLI
-    // records the actually-installed version on first eject.
-    await fs.outputFile(path.join(targetDir, ".zudo-doc.json"), JSON.stringify({
-        packageVersion: ZUDO_DOC_PIN.replace(/^\^/, ""),
-        ejected: {},
-    }, null, 2) + "\n");
+    // .zudo-doc.json is intentionally NOT seeded (locked decision #2653 #6 —
+    // lazy-create on first `zudo-doc eject`). `packages/zudo-doc/src/eject/index.ts`
+    // already tolerates its absence (defaults to `{ packageVersion: "unknown",
+    // ejected: {} }`) and writes the file itself on first successful eject.
     const gitignoreLines = [
         "# Build output",
         "node_modules",
@@ -364,8 +365,10 @@ export async function scaffold(choices) {
 }
 function generatePackageJson(choices) {
     // Intentionally absent from scaffolded deps:
-    //   @takazudo/zudo-doc-md-plugins — private fixture/parity-test asset; not published,
-    //   not for app import. Zero references in generator templates/source.
+    //   @takazudo/zudo-doc-md-plugins — the legacy JS remark/rehype pipeline it
+    //   would have named was retired outright (packages/md-plugins/ deleted,
+    //   #2683); its parity coverage lives in e2e/smoke-markdown-features.spec.ts.
+    //   Zero references in generator templates/source.
     const deps = {
         // zfb engine — distributed as published npm packages (the prebuilt binary
         // ships via an optionalDependency of @takazudo/zfb-<platform>); pinned to
@@ -497,14 +500,15 @@ function generatePackageJson(choices) {
         // pins. No consumer-facing / CLI change.
         // next.76: routine toolchain bump from next.75, adopted in
         // lockstep with the root package.json pins. No consumer-facing / CLI change.
-        // next.77 (current pin): router persistence/history fixes and runtime
-        // island remount support, adopted in lockstep with the root package.json
-        // pins. No scaffold API change.
-        "@takazudo/zfb": "0.1.0-next.77",
-        "@takazudo/zfb-runtime": "0.1.0-next.77",
+        // next.77: router persistence/history fixes and runtime island remount
+        // support, adopted in lockstep with the root package.json pins. No
+        // scaffold API change. next.78 (current pin): production HTML minification
+        // support via minifyHtml, adopted as a zudo-doc default through settings.
+        "@takazudo/zfb": "0.1.0-next.78",
+        "@takazudo/zfb-runtime": "0.1.0-next.78",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.77",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.78",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -564,6 +568,26 @@ function generatePackageJson(choices) {
         // missing copy produces no `pnpm install` warning — which is why this gap
         // shipped silently and only surfaced at build time.
         diff: "^8.0.3",
+        // @takazudo/zdtp — SAME "unconditional at build time despite being an
+        // optional peer" class as `diff` above, discovered empirically while
+        // verifying this generator's own barebone (designTokenPanel: OFF) output
+        // (epic zudolab/zudo-doc#2651, #2660 self-review — a genuine package-level
+        // coupling, not a generator bug; flagged loudly on #2660's completion
+        // comment for a package-side follow-up). Since the #2658 gate-2 fix,
+        // `chrome/derive.tsx`'s `deriveBodyEndIslands` statically imports the REAL
+        // `DesignTokenPanelBootstrap` as the default for EVERY `createChrome`
+        // consumer (so the island auto-mounts with zero host wiring when the
+        // setting is on) — and that component imports `@takazudo/zdtp` at module
+        // scope. So every page that goes through `createChrome` — which is every
+        // page in this project — pulls the zdtp import into the esbuild bundle
+        // graph, `designTokenPanel` setting or not; only RENDERING is gated on
+        // the setting, not the import. Without this dep, `zfb build` fails with
+        // "Could not resolve '@takazudo/zdtp'" even on a fully barebone project.
+        // `preact ^10.29.1` (see the floor comment above) is required for the
+        // same reason. This is the ACCEPTED, permanent contract per #2668 — see
+        // the "@takazudo/zdtp dep implication" note in
+        // packages/zudo-doc/docs/adr/route-injection-seam.md.
+        "@takazudo/zdtp": "0.4.6",
     };
     const devDeps = {
         "@tailwindcss/vite": "^4.2.0",
@@ -571,7 +595,8 @@ function generatePackageJson(choices) {
         typescript: "^5.9.0",
         "@types/node": "^22.0.0",
         "@types/react": "^19.2.0", // needed for preact/compat type resolution
-        "html-validate": "^10.0.0",
+        // html-validate dropped — check:html is no longer a default script
+        // (see the scripts block below; `.htmlvalidate.json` no longer ships).
     };
     if (choices.features.includes("search")) {
         deps["minisearch"] = "^7.2.0";
@@ -587,7 +612,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^3.1.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^3.3.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).
@@ -595,11 +620,6 @@ function generatePackageJson(choices) {
     // claudeResources: tsx is no longer needed. The relocated package plugin
     // (@takazudo/zudo-doc/plugins/claude-resources) imports the runner directly
     // since the package ships compiled dist/ — package-first migration #2321 (#2337).
-    if (choices.features.includes("designTokenPanel")) {
-        // @takazudo/zdtp requires preact >= 10.29.1 — see the preact floor comment
-        // above (~line 382) for why the floor is set there and the coupling this creates.
-        deps["@takazudo/zdtp"] = "0.4.5";
-    }
     if (choices.features.includes("tagGovernance")) {
         // gray-matter is already in `deps` unconditionally (base template uses it),
         // so we only add the tooling deps specific to tags:audit / tags:suggest.
@@ -611,23 +631,19 @@ function generatePackageJson(choices) {
         devDeps["@inquirer/prompts"] = "^8.4.2";
         devDeps["tsx"] = "^4.21.0";
     }
+    // check:html and gen:z-index/check:z-index are DROPPED from the default
+    // scaffold (locked decision, epic #2651 #2660 work item 6):
+    //   - `.htmlvalidate.json` no longer ships — html-validate becomes an
+    //     opt-in extend step (documented in #2664).
+    //   - z-index tokens ship unconditionally from `@takazudo/zudo-doc/theme.css`
+    //     (13 default tiers, epic #2655) — a project only needs its own
+    //     `src/config/z-index-tokens.ts` + codegen scripts when it overrides a
+    //     tier, which is an eject-time decision, not a scaffold-time one.
     const scripts = {
         dev: "zfb dev",
         build: "zfb build",
         preview: "zfb preview",
         check: "zfb check",
-        // NOTE: no `check:pages` here — the host repo's pages/ typecheck
-        // (tsconfig.pages.json, #2018) is host-only for now. The base template's
-        // no-op feature stubs (e.g. doc-history.tsx) are not type-clean against
-        // the pages/lib call sites, so emitting the script would fail on a fresh
-        // scaffold. Revisit once the template stubs carry typed props.
-        "check:html": "html-validate \"dist/**/*.html\"",
-        // Z-index token codegen (#2148): regenerate the GENERATED:Z_INDEX @theme
-        // block in src/styles/global.css from src/config/z-index-tokens.ts, and a
-        // drift check for pre-push/CI. Both ship in base — the z-index token system
-        // is part of every scaffold. Bin provided by @takazudo/zudo-doc (S9b #2334).
-        "gen:z-index": "gen-z-index",
-        "check:z-index": "gen-z-index --check",
     };
     if (choices.features.includes("tagGovernance")) {
         // tags-audit bin is provided by @takazudo/zudo-doc (S9b #2334);
@@ -647,17 +663,17 @@ function generatePackageJson(choices) {
         scripts["setup:doc-skill:both"] =
             "bash scripts/setup-doc-skill.sh --target both";
     }
-    const runCmd = choices.packageManager === "npm" || choices.packageManager === "bun" ? `${choices.packageManager} run` : choices.packageManager;
+    const pm = choices.packageManager;
     // claudeSkills ships the zudo-doc-version-bump skill, whose release workflow
     // calls `<pm> b4push`. Emit a minimal stub so the skill does not hit a
     // "script not found" error on freshly scaffolded projects. Consumers are
     // free to expand this into a richer pre-push pipeline later.
     if (choices.features.includes("claudeSkills")) {
-        scripts["b4push"] = `${runCmd} check && ${runCmd} build`;
+        scripts["b4push"] = `${pmRunCommand(pm, "check")} && ${pmRunCommand(pm, "build")}`;
     }
     if (choices.features.includes("tauri")) {
         scripts["dev:tauri"] = "cargo tauri dev";
-        scripts["build:tauri"] = `${runCmd} build && cargo tauri build`;
+        scripts["build:tauri"] = `${pmRunCommand(pm, "build")} && cargo tauri build`;
     }
     if (choices.features.includes("tauriDev")) {
         scripts["dev:tauri-dev"] = "cd src-tauri-dev && cargo tauri dev";
@@ -668,6 +684,9 @@ function generatePackageJson(choices) {
         version: "0.0.1",
         private: true,
         type: "module",
+        // @takazudo/zfb + @takazudo/zfb-runtime declare engines.node ">=22.0.0";
+        // emit the floor so `<pm> install` warns early on an unsupported Node.
+        engines: { node: ">=22" },
         scripts,
         dependencies: deps,
         devDependencies: devDeps,

package/dist/utils.d.ts

@@ -37,6 +37,16 @@ export declare function initGitRepo(dir: string): GitInitResult;
 export declare function capitalize(str: string): string;
 /** Get a short uppercase label for a language code (e.g. "en" → "EN", "zh-cn" → "ZH-CN"). */
 export declare function getLangLabel(langCode: string): string;
+/**
+ * Build the command that runs a package.json script under `pm`.
+ *
+ * npm and bun BOTH require the `run` verb — `bun build` invokes Bun's bundler,
+ * NOT the package.json `build` script (a real footgun), so bun must emit
+ * `bun run build`. pnpm and yarn accept the bare script name (`pnpm build`).
+ * The single source of truth for this rule across claude-md-gen.ts,
+ * scaffold.ts, and features/tauri.ts.
+ */
+export declare function pmRunCommand(pm: "pnpm" | "npm" | "yarn" | "bun", script: string): string;
 /** Determine the secondary language code when i18n is enabled. */
 export declare function getSecondaryLang(defaultLang: string): string;
 /** Apply a list of regex replacements to a file (if it exists). */

package/dist/utils.js

@@ -114,6 +114,20 @@ export function capitalize(str) {
 export function getLangLabel(langCode) {
     return langCode.toUpperCase();
 }
+/**
+ * Build the command that runs a package.json script under `pm`.
+ *
+ * npm and bun BOTH require the `run` verb — `bun build` invokes Bun's bundler,
+ * NOT the package.json `build` script (a real footgun), so bun must emit
+ * `bun run build`. pnpm and yarn accept the bare script name (`pnpm build`).
+ * The single source of truth for this rule across claude-md-gen.ts,
+ * scaffold.ts, and features/tauri.ts.
+ */
+export function pmRunCommand(pm, script) {
+    return pm === "npm" || pm === "bun"
+        ? `${pm} run ${script}`
+        : `${pm} ${script}`;
+}
 /** Determine the secondary language code when i18n is enabled. */
 export function getSecondaryLang(defaultLang) {
     return defaultLang === "en" ? "ja" : "en";

package/dist/zfb-config-gen.d.ts

@@ -1,25 +1,37 @@
 import type { UserChoices } from "./prompts.js";
 /**
- * Programmatically generate zfb.config.ts from user choices.
+ * Programmatically generate the ONE `zfb.config.ts` a scaffolded project
+ * ships (epic zudolab/zudo-doc#2651, minimal-scaffold Wave 6 #2660).
  *
- * S5b (#2329): collapsed to the thin preset-based shape that mirrors the
- * showcase `zfb.config.ts` after S5a. All collection wiring, plugin
- * descriptors, markdown features, codeHighlight, resolveMarkdownLinks, and
- * trailingSlash are now owned by `zudoDocPreset()` in
- * `@takazudo/zudo-doc/preset`. The generated config spreads the preset
- * result into `defineConfig` and keeps only the project-owned shell fields
- * (`framework`, `port`, `tailwind`, `base`).
+ * Replaces the former `settings-gen.ts` + `zfb-config-gen.ts` pair: there is
+ * no more `src/config/settings.ts` — every user choice becomes a field
+ * passed straight into `zudoDoc({ ... })` (`@takazudo/zudo-doc/config`),
+ * which merges it over the package's own documented defaults and returns a
+ * complete `ZfbConfig`.
  *
- * 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.
- *
- * `_choices` is intentionally unused: post-S5b the emitted config is a
- * CONSTANT. All feature variation is driven by `settings.*` (read at
- * zfb-load time inside `zudoDocPreset()`), so the generated file is byte
- * identical for every feature combination. The parameter is retained only
- * for call-site compatibility (`scaffold.ts` passes `choices`). Do NOT add
- * feature-gated branches here — wire new feature behaviour into
- * `packages/zudo-doc/src/preset.ts` and the project's `settings.ts` instead.
+ * DIFF-FROM-DEFAULTS (locked, #2653 Decision 2): only fields whose resolved
+ * value differs from the matching `ZudoDocConfig` `@default` are emitted —
+ * `siteName` is the one field always emitted. `DEFAULT_MIRROR` below is a
+ * hand-kept copy of `packages/zudo-doc/src/config.ts`'s `DEFAULT_SETTINGS`
+ * for exactly the fields this generator ever sets. It has to be a local
+ * mirror (not an import) because `create-zudo-doc` does not depend on
+ * `@takazudo/zudo-doc` at generator-build time — the package is only ever a
+ * runtime dependency of the SCAFFOLDED project, never of the generator
+ * itself. Keep this mirror in sync by hand whenever `DEFAULT_SETTINGS`
+ * changes for one of the fields listed here.
+ */
+export declare const DEFAULT_MIRROR: Record<string, unknown>;
+/**
+ * Deterministic emission order for the keys of a `desired` config object:
+ * the keys present in `FIELD_ORDER` first (cosmetic reference order), then any
+ * leftover keys NOT in `FIELD_ORDER` appended in ALPHABETICAL order. The
+ * leftover branch exists so a key `buildDesiredConfig()` produces but nobody
+ * added to `FIELD_ORDER` is still emitted (deterministically) rather than
+ * silently dropped — matching what the `FIELD_ORDER` comment promises.
+ */
+export declare function orderDesiredKeys(desiredKeys: readonly string[]): string[];
+/**
+ * Generate the full `zfb.config.ts` source: `defineConfig(zudoDoc({ ... }))`
+ * with only the diff-from-defaults fields.
  */
-export declare function generateZfbConfig(_choices: UserChoices): string;
+export declare function generateZfbConfig(choices: UserChoices): string;