create-zudo-doc 5.18.2 → 5.19.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `create-zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.19.0] - 2026-09-07
+
+### Features
+
+- The first positional argument is now a **destination path**, not just a project name. `create-zudo-doc sub/ref-doc` creates `sub/ref-doc` and derives the project name from the final segment (`ref-doc`); previously it failed with a project-name validation error because the one argument meant both the directory to create and the name written into the generated `package.json`. Relative (`../ref-doc`) and absolute destinations are accepted; `.`, `..`, and a filesystem root are rejected because they name no final segment. `--name` still takes a bare package name and now acts as an explicit override of the derived name while the positional continues to supply the directory. The resolved destination is followed consistently by dependency install, `git init`, and the printed `cd <dest>` hint. The programmatic `CreateOptions` API is unchanged — there `projectName` still doubles as the directory. (5a928d51e)
+
+### Bug Fixes
+
+- The printed `cd` target is quoted when the destination contains whitespace, which a path destination may now legally do, and an empty destination no longer resolves the target directory to the current working directory. (134248eba)
+
+### Other Changes
+
+- The EN and JA `create-zudo-doc` reference pages and the package README document the destination argument: an accepted-forms table, both verbatim error messages, the `--name` override, a scaffolding-into-a-subdirectory example, and a note that the programmatic API has no `destination`. (dc83c4615)
+
 ## [5.18.2] - 2026-09-06
 
 ### Bug Fixes

package/README.md

@@ -42,6 +42,42 @@ pnpm create zudo-doc my-docs \
   --install
 ```
 
+### Destination paths
+
+The positional argument is the **destination** — the directory to scaffold
+into, not just a bare name. It may be a path (relative, `../`-prefixed, or
+absolute), and its **last segment** becomes the project name written to the
+generated `package.json`:
+
+```bash
+# Creates ./sub/ref-doc with the package name "ref-doc"
+pnpm create zudo-doc sub/ref-doc --yes
+```
+
+Only that last segment has to satisfy the project-name grammar (starts with a
+lowercase letter or digit; lowercase letters, digits, dots, underscores, and
+hyphens only; 214 characters max) — the directories leading up to it are just a
+path. `.`, `..`, and a filesystem root are rejected, because they name no last
+segment to derive the project name from.
+
+Use `--name` to override the derived name while the positional argument keeps
+supplying the directory:
+
+```bash
+# Creates ./sub/My-Docs with the package name "ref-doc"
+pnpm create zudo-doc sub/My-Docs --name ref-doc --yes
+```
+
+This makes side-by-side scaffolding straightforward — for example, comparing
+two template versions by generating both into one scratch directory and
+diffing them:
+
+```bash
+pnpm create zudo-doc@5.17.0 /tmp/tpl-check/v5.17 --yes
+pnpm create zudo-doc@5.18.0 /tmp/tpl-check/v5.18 --yes
+diff -r /tmp/tpl-check/v5.17 /tmp/tpl-check/v5.18
+```
+
 ### Locales and translations
 
 `--lang` selects the primary locale. Its pages use the unprefixed
@@ -84,7 +120,8 @@ Built-in UI translations resolve in this order:
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `[project-name]` | Project name (positional arg or `--name`) | prompted |
+| `[destination]` | Directory to scaffold into; may be a path whose last segment becomes the project name | prompted |
+| `--name <name>` | Project name written to `package.json`; overrides the name derived from the destination | destination's last segment |
 | `--lang <code>` | Default language: `en`, `ja`, `zh-cn`, `zh-tw`, `ko`, `es`, `fr`, `de`, `pt` | `en` |
 | `--additional-langs <a,b>` | Ordered additional locale codes; implies i18n and replaces a preset list | none |
 | `--pm <manager>` | Package manager: `pnpm`, `npm`, `yarn`, `bun` | detected |

package/dist/api.js

@@ -1,8 +1,7 @@
-import path from "path";
 import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
 import { parseChangelogPackages, validateChangelogPackages, validateHeaderRightItems, validateMetaTags, } from "./preset.js";
 import { scaffold } from "./scaffold.js";
-import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
+import { initGitRepo, installDependencies, resolveTargetDir, validateProjectName, } from "./utils.js";
 import { resolveLocalePlan } from "./locale-plan.js";
 export { resolveLocalePlan, } from "./locale-plan.js";
 export async function createZudoDoc(options) {
@@ -69,7 +68,9 @@ export async function createZudoDoc(options) {
         changelogPackages,
     };
     await scaffold(choices);
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    // No `destination` on CreateOptions — the programmatic API keeps the
+    // project name doubling as the directory, so the resolver falls back to it.
+    const targetDir = resolveTargetDir(choices);
     if (install) {
         installDependencies(targetDir, choices.packageManager);
     }

package/dist/cli.d.ts

@@ -1,5 +1,14 @@
 export interface CliArgs {
+    /**
+     * The `--name` flag: a bare package name. Kept separate from `destination`
+     * so the locked project-name grammar still rejects a path here.
+     */
     name?: string;
+    /**
+     * The first positional argument: the directory to scaffold into. May be a
+     * path; its final segment becomes the project name unless `--name` overrides.
+     */
+    destination?: string;
     lang?: string;
     additionalLangs?: string[];
     colorSchemeMode?: "single" | "light-dark";

package/dist/cli.js

@@ -2,7 +2,7 @@ import minimist from "minimist";
 import pc from "picocolors";
 import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { parseChangelogPackages, validateChangelogPackages, } from "./preset.js";
-import { validateProjectName } from "./utils.js";
+import { normalizeDestination, splitDestination, validateProjectName, } from "./utils.js";
 import { resolveLocalePlan } from "./locale-plan.js";
 /** Presets are the base layer; an explicitly supplied CLI list replaces it. */
 export function layerAdditionalLangs(presetValue, cliValue) {
@@ -39,12 +39,12 @@ export function parseArgs(argv = process.argv.slice(2)) {
         return argv.some((a) => a === `--${flag}` || a === `--no-${flag}`);
     }
     const args = {};
-    // Project name: first positional arg or --name
-    if (raw.name) {
+    // Destination: first positional arg. Project name: --name (a bare name), or
+    // the destination's final segment when --name is absent.
+    if (raw.name)
         args.name = raw.name;
-    }
-    else if (raw._.length > 0 && typeof raw._[0] === "string") {
-        args.name = raw._[0];
+    if (raw._.length > 0 && typeof raw._[0] === "string") {
+        args.destination = raw._[0];
     }
     if (raw.lang)
         args.lang = raw.lang;
@@ -100,10 +100,15 @@ export function printHelp() {
     const themePackList = THEME_PACKS.map((t) => t.slug).join(", ");
     const featureHelp = FEATURES.map((f) => `  --[no-]${f.cliFlag.padEnd(22)} ${f.hint}`).join("\n");
     console.log(`
-${pc.bold("Usage:")} create-zudo-doc [project-name] [options]
+${pc.bold("Usage:")} create-zudo-doc [destination] [options]
+
+${pc.dim("  destination")}                  Directory to create the project in; may be a path
+                               (e.g. sub/my-docs). Its last segment becomes the
+                               project name. Default: my-docs
 
 ${pc.bold("Options:")}
-  --name <name>                Project name (or first positional arg)
+  --name <name>                Project name written to package.json. Overrides
+                               the name derived from the destination's last segment
   --lang <code>                Default language (${langList})
                                Default: en
   --additional-langs <a,b>     Additional locale codes (ordered; implies i18n)
@@ -137,6 +142,9 @@ ${pc.bold("Examples:")}
   ${pc.dim("# Fully specified")}
   create-zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install
 
+  ${pc.dim("# Scaffold into a subdirectory (package name: ref-doc)")}
+  create-zudo-doc sub/ref-doc --yes
+
   ${pc.dim("# Per-package changelog pages")}
   create-zudo-doc my-docs --changelog-packages core,cli --yes
 `);
@@ -203,5 +211,15 @@ export function validateArgs(args) {
         if (nameError)
             return nameError;
     }
+    if (args.destination !== undefined) {
+        // With --name present the derived segment is overridden, so the final
+        // segment only has to be a legal *directory* name — but a destination that
+        // names no final segment at all (".", "..", "/") is still refused.
+        const result = args.name
+            ? normalizeDestination(args.destination)
+            : splitDestination(args.destination);
+        if (!result.ok)
+            return result.error;
+    }
     return null;
 }

package/dist/index.js

@@ -1,4 +1,3 @@
-import path from "path";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { layerAdditionalLangs, parseArgs, printHelp, validateArgs, } from "./cli.js";
@@ -6,7 +5,7 @@ import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
 import { scaffold } from "./scaffold.js";
-import { installDependencies, initGitRepo, pmRunCommand } from "./utils.js";
+import { destinationLabel, initGitRepo, installDependencies, normalizeDestination, pmRunCommand, resolveTargetDir, } from "./utils.js";
 async function main() {
     const args = parseArgs();
     // Handle --help
@@ -36,6 +35,17 @@ async function main() {
         }
     }
     // CLI args override preset values
+    if (args.destination !== undefined) {
+        // validateArgs() already rejected a destination with no usable final
+        // segment, so this only fails on an input that never reaches here.
+        const dest = normalizeDestination(args.destination);
+        if (dest.ok) {
+            prefilled.destination = dest.destination;
+            prefilled.projectName = dest.finalSegment;
+        }
+    }
+    // --name is a deliberate override of the name derived from the destination's
+    // last segment; the positional keeps supplying the directory either way.
     if (args.name)
         prefilled.projectName = args.name;
     if (args.lang)
@@ -111,7 +121,11 @@ async function main() {
         prefilled.features = { ...featureDefaults, ...prefilled.features };
     }
     const choices = await runPrompts(prefilled);
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    const targetDir = resolveTargetDir(choices);
+    const destination = destinationLabel(choices);
+    // A destination may now contain spaces (only its LAST segment goes through
+    // the project-name grammar), so the `cd` we print has to stay copy-pastable.
+    const cdTarget = /\s/.test(destination) ? `"${destination}"` : destination;
     const s = p.spinner();
     s.start("Scaffolding project...");
     try {
@@ -138,7 +152,7 @@ async function main() {
             initialValue: true,
         });
         if (p.isCancel(result)) {
-            p.outro(`Done! cd ${choices.projectName} and install dependencies manually.`);
+            p.outro(`Done! cd ${cdTarget} and install dependencies manually.`);
             return;
         }
         shouldInstall = result;
@@ -179,10 +193,10 @@ async function main() {
                 break;
         }
     }
-    p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(choices.projectName)}`);
+    p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(destination)}`);
     console.log();
     console.log(`  ${pc.bold("Next steps:")}`);
-    console.log(`  cd ${choices.projectName}`);
+    console.log(`  cd ${cdTarget}`);
     console.log(`  ${pmRunCommand(choices.packageManager, "dev")}`);
     console.log();
 }

package/dist/prompts.d.ts

@@ -1,6 +1,7 @@
 import { type PresetHeaderRightItem, type PresetMetaTagsConfig } from "./preset.js";
 export interface UserChoices {
     projectName: string;
+    destination?: string;
     defaultLang: string;
     additionalLangs?: string[];
     colorSchemeMode: "single" | "light-dark";
@@ -22,6 +23,8 @@ export interface UserChoices {
 }
 export interface PartialChoices {
     projectName?: string;
+    /** See `UserChoices.destination` — CLI-supplied, never prompted for. */
+    destination?: string;
     defaultLang?: string;
     additionalLangs?: string[];
     colorSchemeMode?: "single" | "light-dark";

package/dist/prompts.js

@@ -240,6 +240,7 @@ export async function runPrompts(prefilled = {}) {
         : features.filter((feature) => feature !== "i18n");
     return {
         projectName,
+        destination: prefilled.destination,
         defaultLang: localePlan.defaultLang,
         additionalLangs: prefilled.additionalLangs === undefined
             ? undefined

package/dist/scaffold.d.ts

@@ -31,5 +31,5 @@ export declare function deriveDocSkillName(projectName: string): string;
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^5.18.2";
+export declare const ZUDO_DOC_PIN = "^5.19.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -5,7 +5,7 @@ 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, hasAncestorPnpmWorkspace, pmRunCommand, } from "./utils.js";
+import { capitalize, destinationLabel, hasAncestorPnpmWorkspace, pmRunCommand, resolveTargetDir, } from "./utils.js";
 import { resolveLocalePlan, } from "./locale-plan.js";
 // Kept as a compatibility export from the pre-list API. Internal scaffold
 // emitters consume the resolved LocalePlan directly; see utils.ts for the
@@ -47,7 +47,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.18.2";
+export const ZUDO_DOC_PIN = "^5.19.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -262,11 +262,11 @@ export async function scaffold(choices) {
     if (localePlan.overridesExplicitDisable) {
         console.warn("additional-langs requires i18n; enabling it despite --no-i18n");
     }
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    const targetDir = resolveTargetDir(choices);
     if (await fs.pathExists(targetDir)) {
         const contents = await fs.readdir(targetDir);
         if (contents.length > 0) {
-            throw new Error(`Directory "${choices.projectName}" already exists and is not empty`);
+            throw new Error(`Directory "${destinationLabel(choices)}" already exists and is not empty`);
         }
     }
     // body-foot-util-area.tsx ships the DocHistory component inline (byte-
@@ -892,7 +892,7 @@ function generatePackageJson(choices, localePlan) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so projects with both
         // docHistory and assetViewer off no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.18.2";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.19.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).

package/dist/utils.d.ts

@@ -6,6 +6,63 @@
  * programmatic API.
  */
 export declare function validateProjectName(name: string): string | null;
+export type DestinationPath = {
+    ok: true;
+    destination: string;
+    finalSegment: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type DestinationSplit = {
+    ok: true;
+    destination: string;
+    projectName: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize a destination path and expose its final segment.
+ *
+ * Upward traversal (`../ref-doc`) is **allowed** — `..` is simply a relative
+ * way to name a directory outside the cwd, and absolute destinations are
+ * accepted too, so rejecting it would be inconsistent. `.`, `..`, and a
+ * filesystem root are rejected because they name no final segment.
+ *
+ * `path.resolve()` is deliberately NOT applied before extracting the segment:
+ * resolving `"."` first would turn the *current* directory's basename into an
+ * apparently valid project name and scaffold into the cwd.
+ */
+export declare function normalizeDestination(raw: string): DestinationPath;
+/**
+ * Split a CLI destination argument into the directory to scaffold into and the
+ * package name written to the generated `package.json`.
+ *
+ * The final path segment becomes the project name and goes through the
+ * unchanged `validateProjectName`; everything before it is just a directory
+ * path and is deliberately not validated as a package name. Callers that
+ * supply the name separately (`--name`) use `normalizeDestination` instead, so
+ * a directory segment that is not a legal package name stays acceptable.
+ */
+export declare function splitDestination(raw: string): DestinationSplit;
+/** The two destination-bearing fields every target-dir consumer needs. */
+export interface DestinationChoices {
+    projectName: string;
+    /**
+     * Directory to scaffold into, as given on the CLI. Absent on the
+     * programmatic/preset paths, where the project name is also the directory.
+     */
+    destination?: string;
+}
+/** The destination as the user expressed it — for messages and `cd` output. */
+export declare function destinationLabel(choices: DestinationChoices): string;
+/**
+ * The single source of truth for the absolute directory a scaffold is written
+ * to. Every caller that needs it (scaffold.ts, api.ts, index.ts) must use this
+ * rather than re-deriving it — that is how the three sites used to drift.
+ */
+export declare function resolveTargetDir(choices: DestinationChoices): string;
 export declare function installDependencies(dir: string, pm: string): void;
 export type GitInitResult = {
     status: "ok";

package/dist/utils.js

@@ -3,8 +3,13 @@ import fs from "fs-extra";
 import path from "path";
 import { resolveLocalePlan } from "./locale-plan.js";
 // Project-name grammar (locked by F4 — S4 #2013):
-// /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped, used as both directory
-// name and package name. Mirrors npm's unscoped-name rules + max path safety.
+// /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped. Mirrors npm's
+// unscoped-name rules + max path safety.
+//
+// This grammar covers the *package name* only — the value written to the
+// generated package.json's `name`. The directory the project is written to is
+// a separate concept (`UserChoices.destination`, see `splitDestination` below)
+// and may be any path; only its final segment is checked against this grammar.
 const PROJECT_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
 const PROJECT_NAME_MAX = 214;
 /**
@@ -27,6 +32,81 @@ export function validateProjectName(name) {
     }
     return null;
 }
+/** Trailing path separators, platform-aware (Windows accepts both). */
+const TRAILING_SEPARATORS = path.sep === "\\" ? /[\\/]+$/ : /\/+$/;
+/**
+ * Normalize a destination path and expose its final segment.
+ *
+ * Upward traversal (`../ref-doc`) is **allowed** — `..` is simply a relative
+ * way to name a directory outside the cwd, and absolute destinations are
+ * accepted too, so rejecting it would be inconsistent. `.`, `..`, and a
+ * filesystem root are rejected because they name no final segment.
+ *
+ * `path.resolve()` is deliberately NOT applied before extracting the segment:
+ * resolving `"."` first would turn the *current* directory's basename into an
+ * apparently valid project name and scaffold into the cwd.
+ */
+export function normalizeDestination(raw) {
+    const given = raw.trim();
+    if (given === "") {
+        return { ok: false, error: "Destination path is required" };
+    }
+    // `sub/ref-doc/` and `sub/ref-doc` name the same directory; keep the rest of
+    // the string as the user typed it so messages and `cd` output echo it back.
+    const destination = given.replace(TRAILING_SEPARATORS, "") || given;
+    const finalSegment = path.basename(path.normalize(destination));
+    if (finalSegment === "" || finalSegment === "." || finalSegment === "..") {
+        return {
+            ok: false,
+            error: `Destination "${given}" has no final path segment to name the project. ` +
+                `Pass a destination whose last segment names the project, e.g. "sub/my-docs"`,
+        };
+    }
+    return { ok: true, destination, finalSegment };
+}
+/**
+ * Split a CLI destination argument into the directory to scaffold into and the
+ * package name written to the generated `package.json`.
+ *
+ * The final path segment becomes the project name and goes through the
+ * unchanged `validateProjectName`; everything before it is just a directory
+ * path and is deliberately not validated as a package name. Callers that
+ * supply the name separately (`--name`) use `normalizeDestination` instead, so
+ * a directory segment that is not a legal package name stays acceptable.
+ */
+export function splitDestination(raw) {
+    const normalized = normalizeDestination(raw);
+    if (!normalized.ok)
+        return normalized;
+    const nameError = validateProjectName(normalized.finalSegment);
+    if (nameError) {
+        return {
+            ok: false,
+            error: `Invalid project name "${normalized.finalSegment}" — the last segment of ` +
+                `destination "${raw.trim()}" is used as the package name. ${nameError}`,
+        };
+    }
+    return {
+        ok: true,
+        destination: normalized.destination,
+        projectName: normalized.finalSegment,
+    };
+}
+/** The destination as the user expressed it — for messages and `cd` output. */
+export function destinationLabel(choices) {
+    // `||`, not `??`: an empty destination is as absent as an undefined one, and
+    // letting `""` through would resolve the target directory to the cwd and
+    // scaffold on top of it.
+    return choices.destination || choices.projectName;
+}
+/**
+ * The single source of truth for the absolute directory a scaffold is written
+ * to. Every caller that needs it (scaffold.ts, api.ts, index.ts) must use this
+ * rather than re-deriving it — that is how the three sites used to drift.
+ */
+export function resolveTargetDir(choices) {
+    return path.resolve(process.cwd(), destinationLabel(choices));
+}
 export function installDependencies(dir, pm) {
     const commands = {
         pnpm: "pnpm install",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "5.18.2",
+  "version": "5.19.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",