create-zudo-doc 0.1.0

package/dist/preset.d.ts

@@ -0,0 +1,37 @@
+import type { PartialChoices } from "./prompts.js";
+/**
+ * Header-right item shapes accepted in v1 of preset support. Mirrors
+ * `HeaderRightComponentItem` and `HeaderRightTriggerItem` from
+ * `src/config/settings-types.ts`. The wider `link`/`html` variants are
+ * intentionally rejected for now — they need free-text fields that pollute
+ * the JSON preset schema and the generator UI.
+ */
+export type PresetHeaderRightComponentName = "theme-toggle" | "language-switcher" | "version-switcher" | "github-link" | "search";
+export type PresetHeaderRightTriggerName = "design-token-panel" | "ai-chat";
+export interface PresetHeaderRightComponentItem {
+    type: "component";
+    component: PresetHeaderRightComponentName;
+}
+export interface PresetHeaderRightTriggerItem {
+    type: "trigger";
+    trigger: PresetHeaderRightTriggerName;
+}
+export type PresetHeaderRightItem = PresetHeaderRightComponentItem | PresetHeaderRightTriggerItem;
+export interface PresetJson {
+    projectName?: string;
+    defaultLang?: string;
+    colorSchemeMode?: "single" | "light-dark";
+    singleScheme?: string;
+    lightScheme?: string;
+    darkScheme?: string;
+    defaultMode?: "light" | "dark";
+    respectPrefersColorScheme?: boolean;
+    features?: string[];
+    githubUrl?: string;
+    cjkFriendly?: boolean;
+    packageManager?: "pnpm" | "npm" | "yarn" | "bun";
+    headerRightItems?: PresetHeaderRightItem[];
+}
+export declare function loadPreset(pathOrStdin: string): PartialChoices;
+export declare function validatePreset(json: unknown): string | null;
+export declare function presetToChoices(json: PresetJson): PartialChoices;

package/dist/preset.js

@@ -0,0 +1,156 @@
+import fs from "fs";
+import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+const VALID_HEADER_RIGHT_COMPONENTS = new Set([
+    "theme-toggle",
+    "language-switcher",
+    "version-switcher",
+    "github-link",
+    "search",
+]);
+const VALID_HEADER_RIGHT_TRIGGERS = new Set([
+    "design-token-panel",
+    "ai-chat",
+]);
+export function loadPreset(pathOrStdin) {
+    let raw;
+    if (pathOrStdin === "-") {
+        raw = fs.readFileSync(0, "utf8");
+    }
+    else {
+        raw = fs.readFileSync(pathOrStdin, "utf8");
+    }
+    const json = JSON.parse(raw);
+    const error = validatePreset(json);
+    if (error) {
+        throw new Error(error);
+    }
+    return presetToChoices(json);
+}
+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"]);
+export function validatePreset(json) {
+    if (json === null || typeof json !== "object" || Array.isArray(json)) {
+        return "Preset must be a JSON object";
+    }
+    const p = json;
+    if (p.features !== undefined && !Array.isArray(p.features)) {
+        return `"features" must be an array in preset`;
+    }
+    if (p.defaultLang && !VALID_LANGS.has(p.defaultLang)) {
+        return `Invalid language "${p.defaultLang}" in preset`;
+    }
+    if (p.colorSchemeMode && !["single", "light-dark"].includes(p.colorSchemeMode)) {
+        return `Invalid colorSchemeMode "${p.colorSchemeMode}" in preset`;
+    }
+    if (p.singleScheme && !VALID_SCHEMES.has(p.singleScheme)) {
+        return `Unknown color scheme "${p.singleScheme}" in preset`;
+    }
+    if (p.lightScheme && !VALID_SCHEMES.has(p.lightScheme)) {
+        return `Unknown light scheme "${p.lightScheme}" in preset`;
+    }
+    if (p.darkScheme && !VALID_SCHEMES.has(p.darkScheme)) {
+        return `Unknown dark scheme "${p.darkScheme}" in preset`;
+    }
+    if (p.defaultMode && !["light", "dark"].includes(p.defaultMode)) {
+        return `Invalid defaultMode "${p.defaultMode}" in preset`;
+    }
+    if (p.packageManager && !VALID_PMS.has(p.packageManager)) {
+        return `Invalid packageManager "${p.packageManager}" in preset`;
+    }
+    if (p.cjkFriendly !== undefined && typeof p.cjkFriendly !== "boolean") {
+        return `"cjkFriendly" must be a boolean in preset`;
+    }
+    if (p.headerRightItems !== undefined) {
+        if (!Array.isArray(p.headerRightItems)) {
+            return `"headerRightItems" must be an array in preset`;
+        }
+        for (let i = 0; i < p.headerRightItems.length; i++) {
+            const item = p.headerRightItems[i];
+            if (item === null || typeof item !== "object" || Array.isArray(item)) {
+                return `headerRightItems[${i}] must be an object`;
+            }
+            const t = item.type;
+            if (t === "link" || t === "html") {
+                return `headerRightItems[${i}] type "${t}" is not supported in presets (v1) — edit settings.ts after scaffold`;
+            }
+            if (t === "component") {
+                const component = item.component;
+                if (typeof component !== "string") {
+                    return `headerRightItems[${i}].component must be a string`;
+                }
+                if (!VALID_HEADER_RIGHT_COMPONENTS.has(component)) {
+                    return `headerRightItems[${i}] unknown component "${component}". Allowed: ${[
+                        ...VALID_HEADER_RIGHT_COMPONENTS,
+                    ].join(", ")}`;
+                }
+            }
+            else if (t === "trigger") {
+                const trigger = item.trigger;
+                if (typeof trigger !== "string") {
+                    return `headerRightItems[${i}].trigger must be a string`;
+                }
+                if (!VALID_HEADER_RIGHT_TRIGGERS.has(trigger)) {
+                    return `headerRightItems[${i}] unknown trigger "${trigger}". Allowed: ${[
+                        ...VALID_HEADER_RIGHT_TRIGGERS,
+                    ].join(", ")}`;
+                }
+            }
+            else {
+                return `headerRightItems[${i}] must have type "component" or "trigger" (got ${JSON.stringify(t)})`;
+            }
+        }
+    }
+    // Cross-field validation
+    if (p.colorSchemeMode === "single" && (p.lightScheme || p.darkScheme)) {
+        return `lightScheme/darkScheme are only valid with colorSchemeMode "light-dark"`;
+    }
+    if (p.colorSchemeMode === "light-dark" && p.singleScheme) {
+        return `singleScheme is only valid with colorSchemeMode "single"`;
+    }
+    return null;
+}
+const KNOWN_FEATURES = new Set(FEATURES.map((f) => f.value));
+export function presetToChoices(json) {
+    const choices = {};
+    if (json.projectName)
+        choices.projectName = json.projectName;
+    if (json.defaultLang)
+        choices.defaultLang = json.defaultLang;
+    if (json.colorSchemeMode)
+        choices.colorSchemeMode = json.colorSchemeMode;
+    if (json.singleScheme)
+        choices.singleScheme = json.singleScheme;
+    if (json.lightScheme)
+        choices.lightScheme = json.lightScheme;
+    if (json.darkScheme)
+        choices.darkScheme = json.darkScheme;
+    if (json.defaultMode)
+        choices.defaultMode = json.defaultMode;
+    if (json.respectPrefersColorScheme !== undefined) {
+        choices.respectPrefersColorScheme = json.respectPrefersColorScheme;
+    }
+    if (json.packageManager)
+        choices.packageManager = json.packageManager;
+    if (json.githubUrl !== undefined)
+        choices.githubUrl = json.githubUrl;
+    if (json.cjkFriendly !== undefined)
+        choices.cjkFriendly = json.cjkFriendly;
+    if (json.headerRightItems !== undefined) {
+        choices.headerRightItems = json.headerRightItems;
+    }
+    if (json.features) {
+        // Warn about unrecognized feature names
+        for (const name of json.features) {
+            if (!KNOWN_FEATURES.has(name)) {
+                console.warn(`Warning: unknown feature "${name}" in preset — ignored`);
+            }
+        }
+        const featureMap = {};
+        for (const f of FEATURES) {
+            featureMap[f.value] = json.features.includes(f.value);
+        }
+        choices.features = featureMap;
+    }
+    return choices;
+}

package/dist/prompts.d.ts

@@ -0,0 +1,32 @@
+import type { PresetHeaderRightItem } from "./preset.js";
+export interface UserChoices {
+    projectName: string;
+    defaultLang: string;
+    colorSchemeMode: "single" | "light-dark";
+    singleScheme?: string;
+    lightScheme?: string;
+    darkScheme?: string;
+    respectPrefersColorScheme?: boolean;
+    defaultMode?: "light" | "dark";
+    features: string[];
+    githubUrl?: string;
+    cjkFriendly?: boolean;
+    packageManager: "pnpm" | "npm" | "yarn" | "bun";
+    headerRightItems?: PresetHeaderRightItem[];
+}
+export interface PartialChoices {
+    projectName?: string;
+    defaultLang?: string;
+    colorSchemeMode?: "single" | "light-dark";
+    singleScheme?: string;
+    lightScheme?: string;
+    darkScheme?: string;
+    respectPrefersColorScheme?: boolean;
+    defaultMode?: "light" | "dark";
+    features?: Partial<Record<string, boolean>>;
+    githubUrl?: string;
+    cjkFriendly?: boolean;
+    packageManager?: "pnpm" | "npm" | "yarn" | "bun";
+    headerRightItems?: PresetHeaderRightItem[];
+}
+export declare function runPrompts(prefilled?: PartialChoices): Promise<UserChoices>;

package/dist/prompts.js

@@ -0,0 +1,248 @@
+import * as p from "@clack/prompts";
+import { LIGHT_DARK_PAIRINGS, SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS } from "./constants.js";
+export async function runPrompts(prefilled = {}) {
+    // 1. Project name
+    let projectName;
+    if (prefilled.projectName) {
+        projectName = prefilled.projectName;
+    }
+    else {
+        const result = await p.text({
+            message: "What is your project name?",
+            placeholder: "my-docs",
+            defaultValue: "my-docs",
+            validate(value) {
+                if (!value.trim())
+                    return "Project name is required";
+                if (/^[./]|\.\./.test(value))
+                    return "Project name must not contain path traversal characters";
+                if (/[<>:"|?*\\]/.test(value))
+                    return "Project name contains invalid characters";
+            },
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        projectName = result;
+    }
+    // 2. Default language
+    let defaultLang;
+    if (prefilled.defaultLang) {
+        defaultLang = prefilled.defaultLang;
+    }
+    else {
+        const result = await p.select({
+            message: "Default language:",
+            options: SUPPORTED_LANGS.map((l) => ({
+                value: l.value,
+                label: `${l.label} (${l.value})`,
+            })),
+            initialValue: "en",
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        defaultLang = result;
+    }
+    // 3. Color scheme mode
+    let colorSchemeMode;
+    if (prefilled.colorSchemeMode) {
+        colorSchemeMode = prefilled.colorSchemeMode;
+    }
+    else {
+        const result = await p.select({
+            message: "Color scheme mode:",
+            options: [
+                {
+                    value: "light-dark",
+                    label: "Light & Dark (toggle)",
+                    hint: "Users can switch between light and dark themes",
+                },
+                {
+                    value: "single",
+                    label: "Single scheme",
+                    hint: "One color scheme for the entire site",
+                },
+            ],
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        colorSchemeMode = result;
+    }
+    let singleScheme;
+    let lightScheme;
+    let darkScheme;
+    let respectPrefersColorScheme = prefilled.respectPrefersColorScheme ?? true;
+    let defaultMode = prefilled.defaultMode ?? "dark";
+    if (colorSchemeMode === "single") {
+        if (prefilled.singleScheme) {
+            singleScheme = prefilled.singleScheme;
+        }
+        else {
+            const scheme = await p.select({
+                message: "Choose a color scheme:",
+                options: SINGLE_SCHEMES.map((s) => ({ value: s, label: s })),
+            });
+            if (p.isCancel(scheme))
+                process.exit(0);
+            singleScheme = scheme;
+        }
+    }
+    else {
+        if (prefilled.lightScheme && prefilled.darkScheme) {
+            lightScheme = prefilled.lightScheme;
+            darkScheme = prefilled.darkScheme;
+        }
+        else {
+            const pairingChoice = await p.select({
+                message: "Choose a light/dark pairing:",
+                options: [
+                    ...LIGHT_DARK_PAIRINGS.map((pair) => ({
+                        value: pair.label,
+                        label: `${pair.light} + ${pair.dark}`,
+                        hint: pair.label,
+                    })),
+                    {
+                        value: "custom",
+                        label: "Pick individually",
+                        hint: "Choose light and dark schemes separately",
+                    },
+                ],
+            });
+            if (p.isCancel(pairingChoice))
+                process.exit(0);
+            if (pairingChoice === "custom") {
+                const lightSchemes = SINGLE_SCHEMES.filter((s) => ["Light", "Latte", "Dawn"].some((k) => s.includes(k)));
+                const darkSchemes = SINGLE_SCHEMES.filter((s) => !["Light", "Latte", "Dawn"].some((k) => s.includes(k)));
+                const light = await p.select({
+                    message: "Choose light scheme:",
+                    options: lightSchemes.map((s) => ({ value: s, label: s })),
+                });
+                if (p.isCancel(light))
+                    process.exit(0);
+                lightScheme = light;
+                const dark = await p.select({
+                    message: "Choose dark scheme:",
+                    options: darkSchemes.map((s) => ({ value: s, label: s })),
+                });
+                if (p.isCancel(dark))
+                    process.exit(0);
+                darkScheme = dark;
+            }
+            else {
+                const pairing = LIGHT_DARK_PAIRINGS.find((pair) => pair.label === pairingChoice);
+                if (pairing) {
+                    lightScheme = pairing.light;
+                    darkScheme = pairing.dark;
+                }
+            }
+        }
+        // Default mode
+        if (prefilled.defaultMode === undefined) {
+            const modeResult = await p.select({
+                message: "Default color mode:",
+                options: [
+                    {
+                        value: "dark",
+                        label: "Dark",
+                        hint: "Start in dark mode",
+                    },
+                    {
+                        value: "light",
+                        label: "Light",
+                        hint: "Start in light mode",
+                    },
+                ],
+            });
+            if (p.isCancel(modeResult))
+                process.exit(0);
+            defaultMode = modeResult;
+        }
+        // Respect system preference
+        if (prefilled.respectPrefersColorScheme === undefined) {
+            const respect = await p.confirm({
+                message: "Respect system color scheme preference?",
+                initialValue: true,
+            });
+            if (p.isCancel(respect))
+                process.exit(0);
+            respectPrefersColorScheme = respect;
+        }
+    }
+    // 4. Features
+    let features;
+    if (prefilled.features) {
+        // Build features from explicit overrides + defaults
+        features = FEATURES.filter((f) => {
+            if (f.value in prefilled.features) {
+                return prefilled.features[f.value];
+            }
+            return f.default;
+        }).map((f) => f.value);
+    }
+    else {
+        const result = await p.multiselect({
+            message: "Include extra features:",
+            options: FEATURES.map((f) => ({
+                value: f.value,
+                label: f.label,
+                hint: f.hint,
+            })),
+            initialValues: FEATURES.filter((f) => f.default).map((f) => f.value),
+            required: false,
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        features = result;
+    }
+    // 5. GitHub URL (drives header GitHub icon + view-source link)
+    let githubUrl = prefilled.githubUrl;
+    if (githubUrl === undefined) {
+        const result = await p.text({
+            message: "GitHub repository URL (optional, leave blank to disable):",
+            placeholder: "https://github.com/you/your-repo",
+            defaultValue: "",
+            validate(value) {
+                if (!value)
+                    return;
+                if (!/^https?:\/\//.test(value))
+                    return "URL must start with http(s)://";
+            },
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        githubUrl = result;
+    }
+    // 6. Package manager
+    let packageManager;
+    if (prefilled.packageManager) {
+        packageManager = prefilled.packageManager;
+    }
+    else {
+        const result = await p.select({
+            message: "Package manager:",
+            options: [
+                { value: "pnpm", label: "pnpm", hint: "Recommended" },
+                { value: "npm", label: "npm" },
+                { value: "yarn", label: "yarn" },
+                { value: "bun", label: "bun" },
+            ],
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        packageManager = result;
+    }
+    return {
+        projectName,
+        defaultLang,
+        colorSchemeMode,
+        singleScheme,
+        lightScheme,
+        darkScheme,
+        respectPrefersColorScheme,
+        defaultMode,
+        features,
+        githubUrl,
+        cjkFriendly: prefilled.cjkFriendly,
+        packageManager,
+        headerRightItems: prefilled.headerRightItems,
+    };
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,4 @@
+import type { UserChoices } from "./prompts.js";
+import { getSecondaryLang } from "./utils.js";
+export { getSecondaryLang };
+export declare function scaffold(choices: UserChoices): Promise<void>;