create-zudo-doc 3.2.0 → 4.0.0

package/dist/features/tag-governance.js

@@ -1,16 +1,44 @@
+import fs from "fs-extra";
+import path from "path";
+import { getSecondaryLang } from "../utils.js";
 /**
  * Tag governance feature.
  *
- * Ships the tag audit and suggest scripts. Settings (`tagVocabulary`,
- * `tagGovernance`) are emitted by `settings-gen.ts`; devDeps and
- * `tags:audit` / `tags:suggest` package scripts are added in
- * `scaffold.ts#generatePackageJson`.
- *
- * `src/config/tag-vocabulary.ts` and `tag-vocabulary-types.ts` stay in the
- * base template because `src/utils/tags.ts` and `settings-types.ts` import
- * from them regardless of whether governance is on.
+ * Writes one project-owned tag vocabulary module. Its named vocabulary export
+ * feeds zfb while its default TagCliConfig export feeds both package-owned
+ * bins through an explicit `--config` package-script argument.
  */
-export const tagGovernanceFeature = () => ({
+export const tagGovernanceFeature = (choices) => ({
     name: "tagGovernance",
     injections: [],
+    postProcess: async (targetDir) => {
+        const vocabPath = path.join(targetDir, "src/config/tag-vocabulary.ts");
+        if (!(await fs.pathExists(vocabPath))) {
+            const contentDirs = choices.features.includes("i18n")
+                ? `[
+  "src/content/docs",
+  "src/content/docs-${getSecondaryLang(choices.defaultLang)}",
+]`
+                : `["src/content/docs"]`;
+            await fs.outputFile(vocabPath, `import type { TagCliConfig } from "@takazudo/zudo-doc/tags-audit";
+import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
+
+// Starter (empty) tag vocabulary — add an entry per tag you use in doc
+// frontmatter so \`pnpm tags:audit\` can validate it. This named export is
+// also consumed by zfb.config.ts as tagVocabularyEntries.
+export const tagVocabulary: TagVocabularyEntry[] = [];
+
+// Package scripts pass this module to the package-owned audit/suggest bins.
+// Paths are resolved from the project root.
+const tagCliConfig = {
+  contentDirs: ${contentDirs},
+  vocabulary: tagVocabulary,
+  governance: "warn",
+  vocabularyActive: true,
+} satisfies TagCliConfig;
+
+export default tagCliConfig;
+`);
+        }
+    },
 });

package/dist/features/tauri.d.ts

@@ -2,15 +2,18 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Tauri feature.
  *
- * #2052: the FindInPageInit island (Cmd/Ctrl+F find bar for the Tauri
- * WebView, where the browser-native find UI is unavailable) is wired into
- * `pages/lib/_body-end-islands.tsx` via the three injections below — import,
- * displayName, and Island mount. zfb's island scanner only registers
- * components reachable through static import chains (page → wrapper →
- * component), so without this injection the feature-copied component files
- * are orphaned dead code that never hydrates. The find-match highlight CSS
- * is unconditional in `templates/base/src/styles/global.css` (matches host);
- * the component runtime-gates itself (renders null unless
- * `window.__TAURI_INTERNALS__` exists), so no settings field is needed.
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660): the
+ * `src-tauri/**` Rust shell is a genuine, unconditional file copy (no
+ * package equivalent — kept exactly as before).
+ *
+ * The FindInPageInit island (Cmd/Ctrl+F find bar, #2052) is now
+ * package-owned (`@takazudo/zudo-doc`, #2689) instead of a template file
+ * copy — `zfb-config-gen.ts`'s `buildDesiredConfig()` sets
+ * `findInPage: true` whenever this feature is selected (#2690), which mounts
+ * the package's `FindInPageInit` island via `zudoDocPreset()`. There is no
+ * separate `findInPage` feature module or CLI flag; it rides this one. The
+ * island self-gates on `window.__TAURI_INTERNALS__`, so it's a safe no-op in
+ * a plain browser build even though `findInPage: true` is unconditionally
+ * emitted for every tauri-feature scaffold.
  */
 export declare const tauriFeature: FeatureModule;

package/dist/features/tauri.js

@@ -1,60 +1,26 @@
 import fs from "fs-extra";
 import path from "path";
+import { pmRunCommand } from "../utils.js";
 /**
  * Tauri feature.
  *
- * #2052: the FindInPageInit island (Cmd/Ctrl+F find bar for the Tauri
- * WebView, where the browser-native find UI is unavailable) is wired into
- * `pages/lib/_body-end-islands.tsx` via the three injections below — import,
- * displayName, and Island mount. zfb's island scanner only registers
- * components reachable through static import chains (page → wrapper →
- * component), so without this injection the feature-copied component files
- * are orphaned dead code that never hydrates. The find-match highlight CSS
- * is unconditional in `templates/base/src/styles/global.css` (matches host);
- * the component runtime-gates itself (renders null unless
- * `window.__TAURI_INTERNALS__` exists), so no settings field is needed.
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660): the
+ * `src-tauri/**` Rust shell is a genuine, unconditional file copy (no
+ * package equivalent — kept exactly as before).
+ *
+ * The FindInPageInit island (Cmd/Ctrl+F find bar, #2052) is now
+ * package-owned (`@takazudo/zudo-doc`, #2689) instead of a template file
+ * copy — `zfb-config-gen.ts`'s `buildDesiredConfig()` sets
+ * `findInPage: true` whenever this feature is selected (#2690), which mounts
+ * the package's `FindInPageInit` island via `zudoDocPreset()`. There is no
+ * separate `findInPage` feature module or CLI flag; it rides this one. The
+ * island self-gates on `window.__TAURI_INTERNALS__`, so it's a safe no-op in
+ * a plain browser build even though `findInPage: true` is unconditionally
+ * emitted for every tauri-feature scaffold.
  */
 export const tauriFeature = (choices) => ({
     name: "tauri",
-    injections: [
-        // 1. Import the island entry. Inserted AFTER the
-        //    `// @slot:body-end-islands:imports` anchor.
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "// @slot:body-end-islands:imports",
-            position: "after",
-            content: `import FindInPageInit from "@/components/find-in-page-init";`,
-        },
-        // 2. Stable island marker name (same belt-and-braces guard as the
-        //    sibling islands in the file). Inserted AFTER the
-        //    `// @slot:body-end-islands:display-names` anchor.
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "// @slot:body-end-islands:display-names",
-            position: "after",
-            content: `(FindInPageInit as { displayName?: string }).displayName = "FindInPageInit";`,
-        },
-        // 3. Island mount. Inserted AFTER the
-        //    `{/* @slot:body-end-islands:extra-islands */}` anchor.
-        //    when="load" (not "idle"): the island's job is to intercept
-        //    Cmd/Ctrl+F via a keydown listener, so it must hydrate as soon as
-        //    the islands runtime mounts — same rationale as the
-        //    clientRouterBootstrap click intercept above it. Deferring to idle
-        //    would leave a post-load window where Cmd+F does nothing, which is
-        //    the very bug this injection fixes.
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "{/* @slot:body-end-islands:extra-islands */}",
-            position: "after",
-            content: `      {/* Tauri-only find-in-page (Cmd/Ctrl+F) bar. Renders null outside
-          a Tauri WebView, so the island is inert in plain browser builds
-          of the same scaffold. */}
-      {Island({
-        when: "load",
-        children: <FindInPageInit />,
-      }) as unknown as VNode}`,
-        },
-    ],
+    injections: [],
     postProcess: async (targetDir) => {
         // Patch Cargo.toml package name
         const cargoPath = path.join(targetDir, "src-tauri/Cargo.toml");
@@ -76,9 +42,7 @@ export const tauriFeature = (choices) => ({
             content = content.replace(/"productName": "ZudoDoc"/, `"productName": "${productName}"`);
             content = content.replace(/"identifier": "com.zudolab.zudo-doc"/, `"identifier": "${identifier}"`);
             // Patch beforeDevCommand for the chosen package manager
-            const devCmd = choices.packageManager === "npm" || choices.packageManager === "bun"
-                ? `${choices.packageManager} run dev`
-                : `${choices.packageManager} dev`;
+            const devCmd = pmRunCommand(choices.packageManager, "dev");
             content = content.replace(/"beforeDevCommand": "pnpm dev"/, `"beforeDevCommand": "${devCmd}"`);
             await fs.writeFile(confPath, content);
         }

package/dist/features/theme-pack-switcher.d.ts

@@ -0,0 +1,11 @@
+import type { FeatureModule } from "../compose.js";
+/**
+ * themePackSwitcher feature (theme pack ADR #2818).
+ *
+ * Purely a `zudoDoc({ themePackSwitcher: true })` field (see
+ * `zfb-config-gen.ts`) — the bottom-right switcher flyout and its browse-all
+ * dialog are PACKAGE-INJECTED (`@takazudo/zudo-doc`'s theme-pack-provider /
+ * theme-pack-sync + the flyout/dialog islands), gated on
+ * `settings.themePackSwitcher`. There is nothing to copy or postProcess.
+ */
+export declare const themePackSwitcherFeature: FeatureModule;

package/dist/features/theme-pack-switcher.js

@@ -0,0 +1,13 @@
+/**
+ * themePackSwitcher feature (theme pack ADR #2818).
+ *
+ * Purely a `zudoDoc({ themePackSwitcher: true })` field (see
+ * `zfb-config-gen.ts`) — the bottom-right switcher flyout and its browse-all
+ * dialog are PACKAGE-INJECTED (`@takazudo/zudo-doc`'s theme-pack-provider /
+ * theme-pack-sync + the flyout/dialog islands), gated on
+ * `settings.themePackSwitcher`. There is nothing to copy or postProcess.
+ */
+export const themePackSwitcherFeature = () => ({
+    name: "themePackSwitcher",
+    injections: [],
+});

package/dist/features/versioning.d.ts

@@ -2,30 +2,18 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Versioning feature.
  *
- * The pages/lib wrappers gate `VersionSwitcher` and `VersionBanner` on
- * `settings.versions`. Doc-layout flow is handled by route enumerators +
- * `_inline-version-switcher.tsx`. This feature copies versioning page
- * templates from `templates/features/versioning/files/` via
- * `copyFeatureFiles` (compose.ts), and injects nothing into `global.css`.
+ * Purely a `zudoDoc({ versions: [] })` field (see `zfb-config-gen.ts`) — the
+ * versioned doc routes (`/docs/versions`, `/v/[version]/docs/[[...slug]]`,
+ * and their i18n counterparts) are PACKAGE-INJECTED
+ * (`settings.packageOwnedRoutes`, default on) and render through the shared
+ * `renderDocPage` chrome. `templates/features/versioning/files/` has been
+ * empty since #2390 — there is no host stub left to copy or postProcess.
  *
- * W7C (#1738): the versioning feature ships pages under
- * `templates/features/versioning/files/pages/`:
- *
- *   lib/_versions-page.tsx                  (always — versions-listing renderer)
- *
- * The versioned DOC routes — `/docs/versions`, `/v/[version]/docs/[[...slug]]`,
- * and `/v/[version]/[locale]/docs/[[...slug]]` — are now PACKAGE-INJECTED
- * (packageOwnedRoutes); their host catch-all stubs were deleted from the
- * template in #2390 (supersedes #2377) so generated projects render them via
- * injection through `@takazudo/zudo-doc`'s `_chrome` chrome (which wires the
- * MDX content components). The package route is the functional equivalent of
- * the old stub (it enumerates `settings.versions` and renders via the shared
- * `renderDocPage`).
- *
- * `copyFeatureFiles` (compose.ts) auto-copies everything under `files/`.
- * postProcess is now a defensive no-op: the i18n-gated stubs it strips
- * (`[locale]/docs/versions.tsx`, `v/[version]/[locale]/**`) no longer ship in
- * the template, but the cleanup is kept so a re-added stub can never leak an
- * orphan locale route into a single-locale project.
+ * Known limitation (pre-existing, not introduced by the minimal-scaffold
+ * cutover — inherited from the same injected-DYNAMIC-route dev-mode gap the
+ * locked manifest's `pages/docs/[[...slug]].tsx` stub exists to fix for the
+ * primary doc route, tracked as a #2667 follow-up): the versioned doc
+ * routes may still 404 in `zfb dev` since versioning has no stub of its own
+ * in the locked manifest. `zfb build` is unaffected.
  */
 export declare const versioningFeature: FeatureModule;

package/dist/features/versioning.js

@@ -1,47 +1,21 @@
-import fs from "fs-extra";
-import path from "path";
 /**
  * Versioning feature.
  *
- * The pages/lib wrappers gate `VersionSwitcher` and `VersionBanner` on
- * `settings.versions`. Doc-layout flow is handled by route enumerators +
- * `_inline-version-switcher.tsx`. This feature copies versioning page
- * templates from `templates/features/versioning/files/` via
- * `copyFeatureFiles` (compose.ts), and injects nothing into `global.css`.
+ * Purely a `zudoDoc({ versions: [] })` field (see `zfb-config-gen.ts`) — the
+ * versioned doc routes (`/docs/versions`, `/v/[version]/docs/[[...slug]]`,
+ * and their i18n counterparts) are PACKAGE-INJECTED
+ * (`settings.packageOwnedRoutes`, default on) and render through the shared
+ * `renderDocPage` chrome. `templates/features/versioning/files/` has been
+ * empty since #2390 — there is no host stub left to copy or postProcess.
  *
- * W7C (#1738): the versioning feature ships pages under
- * `templates/features/versioning/files/pages/`:
- *
- *   lib/_versions-page.tsx                  (always — versions-listing renderer)
- *
- * The versioned DOC routes — `/docs/versions`, `/v/[version]/docs/[[...slug]]`,
- * and `/v/[version]/[locale]/docs/[[...slug]]` — are now PACKAGE-INJECTED
- * (packageOwnedRoutes); their host catch-all stubs were deleted from the
- * template in #2390 (supersedes #2377) so generated projects render them via
- * injection through `@takazudo/zudo-doc`'s `_chrome` chrome (which wires the
- * MDX content components). The package route is the functional equivalent of
- * the old stub (it enumerates `settings.versions` and renders via the shared
- * `renderDocPage`).
- *
- * `copyFeatureFiles` (compose.ts) auto-copies everything under `files/`.
- * postProcess is now a defensive no-op: the i18n-gated stubs it strips
- * (`[locale]/docs/versions.tsx`, `v/[version]/[locale]/**`) no longer ship in
- * the template, but the cleanup is kept so a re-added stub can never leak an
- * orphan locale route into a single-locale project.
+ * Known limitation (pre-existing, not introduced by the minimal-scaffold
+ * cutover — inherited from the same injected-DYNAMIC-route dev-mode gap the
+ * locked manifest's `pages/docs/[[...slug]].tsx` stub exists to fix for the
+ * primary doc route, tracked as a #2667 follow-up): the versioned doc
+ * routes may still 404 in `zfb dev` since versioning has no stub of its own
+ * in the locked manifest. `zfb build` is unaffected.
  */
-export const versioningFeature = (choices) => ({
+export const versioningFeature = () => ({
     name: "versioning",
-    postProcess: async (targetDir) => {
-        if (!choices.features.includes("i18n")) {
-            const localeVersions = path.join(targetDir, "pages", "[locale]", "docs", "versions.tsx");
-            if (await fs.pathExists(localeVersions)) {
-                await fs.remove(localeVersions);
-            }
-            const localeVersionedDocs = path.join(targetDir, "pages", "v", "[version]", "[locale]");
-            if (await fs.pathExists(localeVersionedDocs)) {
-                await fs.remove(localeVersionedDocs);
-            }
-        }
-    },
     injections: [],
 });

package/dist/index.js

@@ -6,7 +6,7 @@ import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
 import { scaffold } from "./scaffold.js";
-import { installDependencies, initGitRepo } from "./utils.js";
+import { installDependencies, initGitRepo, pmRunCommand } from "./utils.js";
 async function main() {
     const args = parseArgs();
     // Handle --help
@@ -55,6 +55,8 @@ async function main() {
     if (args.respectSystemPreference !== undefined) {
         prefilled.respectPrefersColorScheme = args.respectSystemPreference;
     }
+    if (args.themePack)
+        prefilled.themePack = args.themePack;
     if (args.pm)
         prefilled.packageManager = args.pm;
     if (args.githubUrl !== undefined)
@@ -91,6 +93,7 @@ async function main() {
         else {
             prefilled.singleScheme ??= "Default Dark";
         }
+        prefilled.themePack ??= "default";
         prefilled.packageManager ??= "pnpm";
         prefilled.githubUrl ??= "";
         // For features: set defaults for any not explicitly specified
@@ -173,8 +176,7 @@ async function main() {
     console.log();
     console.log(`  ${pc.bold("Next steps:")}`);
     console.log(`  cd ${choices.projectName}`);
-    const runCmd = choices.packageManager === "npm" ? "npm run" : choices.packageManager;
-    console.log(`  ${runCmd} dev`);
+    console.log(`  ${pmRunCommand(choices.packageManager, "dev")}`);
     console.log();
 }
 main().catch((err) => {

package/dist/preset.d.ts

@@ -35,6 +35,8 @@ export interface PresetJson {
     darkScheme?: string;
     defaultMode?: "light" | "dark";
     respectPrefersColorScheme?: boolean;
+    /** Theme pack slug (ADR #2818 Decision 7), validated against THEME_PACKS. */
+    themePack?: string;
     features?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;

package/dist/preset.js

@@ -1,5 +1,5 @@
 import fs from "fs";
-import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { validateProjectName } from "./utils.js";
 const VALID_HEADER_RIGHT_COMPONENTS = new Set([
     "theme-toggle",
@@ -30,6 +30,7 @@ export function loadPreset(pathOrStdin) {
 const VALID_LANGS = new Set(SUPPORTED_LANGS.map((l) => l.value));
 const VALID_SCHEMES = new Set(SINGLE_SCHEMES);
 const VALID_PMS = new Set(["pnpm", "npm", "yarn", "bun"]);
+const VALID_THEME_PACKS = new Set(THEME_PACKS.map((t) => t.slug));
 export function validatePreset(json) {
     if (json === null || typeof json !== "object" || Array.isArray(json)) {
         return "Preset must be a JSON object";
@@ -66,6 +67,14 @@ export function validatePreset(json) {
     if (p.defaultMode && !["light", "dark"].includes(p.defaultMode)) {
         return `Invalid defaultMode "${p.defaultMode}" in preset`;
     }
+    if (p.themePack !== undefined) {
+        if (typeof p.themePack !== "string") {
+            return `"themePack" must be a string in preset`;
+        }
+        if (!VALID_THEME_PACKS.has(p.themePack)) {
+            return `Unknown theme pack "${p.themePack}" in preset. Available: ${[...VALID_THEME_PACKS].join(", ")}`;
+        }
+    }
     if (p.packageManager && !VALID_PMS.has(p.packageManager)) {
         return `Invalid packageManager "${p.packageManager}" in preset`;
     }
@@ -174,6 +183,8 @@ export function presetToChoices(json) {
     if (json.respectPrefersColorScheme !== undefined) {
         choices.respectPrefersColorScheme = json.respectPrefersColorScheme;
     }
+    if (json.themePack)
+        choices.themePack = json.themePack;
     if (json.packageManager)
         choices.packageManager = json.packageManager;
     if (json.githubUrl !== undefined)

package/dist/prompts.d.ts

@@ -8,6 +8,7 @@ export interface UserChoices {
     darkScheme?: string;
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
+    themePack?: string;
     features: string[];
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
@@ -26,6 +27,7 @@ export interface PartialChoices {
     darkScheme?: string;
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
+    themePack?: string;
     features?: Partial<Record<string, boolean>>;
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;

package/dist/prompts.js

@@ -1,5 +1,5 @@
 import * as p from "@clack/prompts";
-import { SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS } from "./constants.js";
+import { SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { validateProjectName } from "./utils.js";
 export async function runPrompts(prefilled = {}) {
     // 1. Project name
@@ -124,6 +124,26 @@ export async function runPrompts(prefilled = {}) {
             respectPrefersColorScheme = respect;
         }
     }
+    // 3.5 Theme pack (ADR #2818 Decision 7) — placed between the color-scheme
+    // block above and the features multiselect below (locked spec, #2823).
+    let themePack;
+    if (prefilled.themePack) {
+        themePack = prefilled.themePack;
+    }
+    else {
+        const result = await p.select({
+            message: "Theme pack:",
+            options: THEME_PACKS.map((t) => ({
+                value: t.slug,
+                label: t.label,
+                hint: t.hint,
+            })),
+            initialValue: "default",
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        themePack = result;
+    }
     // 4. Features
     let features;
     if (prefilled.features) {
@@ -196,6 +216,7 @@ export async function runPrompts(prefilled = {}) {
         darkScheme,
         respectPrefersColorScheme,
         defaultMode,
+        themePack,
         features,
         explicitlyDisabledFeatures: prefilled.explicitlyDisabledFeatures,
         githubUrl,

package/dist/scaffold.d.ts

@@ -2,14 +2,21 @@ import type { UserChoices } from "./prompts.js";
 import { getSecondaryLang } 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 declare const ZUDO_DOC_PIN = "^3.2.0";
+export declare const ZUDO_DOC_PIN = "^4.0.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;