create-zudo-doc 5.19.0 → 5.20.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.
 
+## [Unreleased]
+
+No unreleased changes.
+
+## [5.20.0] - 2026-09-09
+
+### Bug Fixes
+
+- Made the generated documentation-skill setup script work on stock macOS Bash 3.2 and corrected its locale/config handling, including checking that the documentation symlink exists before emitting locale guidance. (`85b603e33`, `f6b699fe0`)
+- Fixed the generated link checker to recognize IDs and links when quoted attributes contain `>`, and reduced repeated scanning by parsing each page once. (`0e52271b9`, `7c0144e51`)
+
+### Other Changes
+
+- Updated the Design Token Panel feature's emitted `@takazudo/zdtp` pin to `0.7.0`. Fresh scaffolds use the compatible panel integration without a migration. (`e0fc27fbd`, `9554dbbea`)
+
+## [5.19.1] - 2026-09-08
+
+### Other Changes
+
+- A generated project's `package.json` now pins `@takazudo/zfb`, `@takazudo/zfb-runtime`, and `@takazudo/zfb-md-wasm` at `2.16.0`, and `@takazudo/zdtp` at `0.5.2` when the Design Token Panel feature is enabled (`47c149385`). Both upstream releases are drop-in for a fresh scaffold — zfb 2.16.0 fixes an `ETXTBSY` crash when first executing a just-written esbuild binary, zdtp 0.5.2 is additive — so no public API, export, config default, or engine requirement moves and a fresh scaffold needs no migration.
+
 ## [5.19.0] - 2026-09-07
 
 ### Features

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.19.0";
+export declare const ZUDO_DOC_PIN = "^5.20.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -47,7 +47,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.19.0";
+export const ZUDO_DOC_PIN = "^5.20.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -759,9 +759,22 @@ function generatePackageJson(choices, localePlan) {
         // four shipped wasm binaries are byte-size identical to 2.15.0 (rebuild
         // noise only), and no public API, export, config default, or engine
         // requirement moves, so a fresh scaffold needs no migration.
-        "@takazudo/zfb": "2.15.1",
-        "@takazudo/zfb-runtime": "2.15.1",
-        "@takazudo/zfb-md-wasm": "2.15.1",
+        // 2.16.0: one upstream bug fix, plus a documentation-only md-wasm change.
+        // zfb's esbuild version-gate spawn (`ensure_binary_verified`) now retries on
+        // `ETXTBSY` through zfb-build's existing retry loop instead of a bare
+        // `.output()`, so a build no longer dies with `Text file busy (os error 26)`
+        // on the first exec of a binary a packaged zfb has only just written to a
+        // tempdir. The fix ships in the five platform binary packages, which roll to
+        // 2.16.0 with the wrapper. zfb-runtime and zfb-adapter-cloudflare have no
+        // package-specific change; md-wasm changes only its README (a digest
+        // disclaimer beside the shipped-size table), keeps every artifact at its
+        // 2.15.1 byte size, and moves all four wasm SHA-256 digests as every release
+        // does — pin by semver, as here, and there is nothing to re-pin. No public
+        // API, export, config default, or engine requirement moves, so a fresh
+        // scaffold needs no migration.
+        "@takazudo/zfb": "2.16.0",
+        "@takazudo/zfb-runtime": "2.16.0",
+        "@takazudo/zfb-md-wasm": "2.16.0",
         // @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
@@ -869,7 +882,7 @@ function generatePackageJson(choices, localePlan) {
         // `@takazudo/zdtp/styles.css` (see features/design-token-panel.ts). Both are
         // no-ops with the feature off, so an OFF project must not carry the dep
         // (#4009 / #4018 — it was unconditional until then, see the `deps` block).
-        deps["@takazudo/zdtp"] = "0.5.1";
+        deps["@takazudo/zdtp"] = "0.7.0";
     }
     if (choices.features.includes("docHistory") ||
         choices.features.includes("assetViewer")) {
@@ -892,7 +905,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.19.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.20.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/package.json

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

package/templates/base/scripts/check-links.js

@@ -445,13 +445,26 @@ function decodeHtmlAttributeValue(value) {
   );
 }
 
-// Single shared anchor scan. `extractHtmlLinks` and
-// `extractProtocolRelativeHtmlLinks` classify the SAME set of `<a href>`
-// matches into disjoint buckets, so the grammar and the incremental line
-// counting live here once — a fix to the anchor regex must never reach only
-// one of the two callers.
+// Attribute-scan grammar shared by the anchor and id scans below. A quoted
+// attribute value may legally contain ">" (title="a > b"), so bounding an
+// attribute scan with [^>] silently drops the whole tag: a lost id is a noisy
+// false STRICT FAIL, while a lost href means the link is never checked at all
+// (#4046). This run crosses ">" only inside quotes, and a decoy `href=`/`id=`
+// written as text inside another attribute's value stays unreachable because a
+// quoted span is consumed whole. Each alternative starts with a distinct
+// character, so the repetition backtracks linearly.
+const HTML_ATTRIBUTE_RUN = /(?:"[^"]*"|'[^']*'|[^>"'])/.source;
+const HTML_ATTRIBUTE_VALUE = /(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))/.source;
+
+// Single shared anchor scan. Its one consumer, `classifyHtmlAnchorHrefs`,
+// splits these matches into disjoint buckets, so the grammar and the
+// incremental line counting live here once and every bucket sees a fix to the
+// anchor regex.
 function* iterateHtmlAnchorHrefs(html) {
-  const regex = /<a(?=\s)[^>]*?\shref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))[^>]*>/gi;
+  const regex = new RegExp(
+    `<a(?=\\s)${HTML_ATTRIBUTE_RUN}*?\\shref\\s*=\\s*${HTML_ATTRIBUTE_VALUE}${HTML_ATTRIBUTE_RUN}*>`,
+    "gi",
+  );
   let match;
   let lastIndex = 0;
   let line = 1;
@@ -462,30 +475,39 @@ function* iterateHtmlAnchorHrefs(html) {
   }
 }
 
-export function extractHtmlLinks(html) {
+// One anchor pass, two disjoint buckets: internal links to resolve, and the
+// protocol-relative hrefs that are external for resolution purposes but worth
+// reporting informationally (see #3921/#3930). The dist walk calls this once
+// per page; `extractHtmlLinks` / `extractProtocolRelativeHtmlLinks` below are
+// single-bucket views for callers that want only one of the two.
+export function classifyHtmlAnchorHrefs(html) {
   const links = [];
+  const protocolRelative = [];
   for (const { href, line } of iterateHtmlAnchorHrefs(html)) {
-    if (/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
+    if (/^\/\//.test(href)) {
+      protocolRelative.push({ href, line });
+      continue;
+    }
+    if (/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
     links.push({ href, line });
   }
-  return links;
+  return { links, protocolRelative };
+}
+
+export function extractHtmlLinks(html) {
+  return classifyHtmlAnchorHrefs(html).links;
 }
 
-// Informational counterpart to extractHtmlLinks: same scan, but keeps only the
-// protocol-relative hrefs that extractHtmlLinks classifies as external and
-// skips (see #3921/#3930).
 export function extractProtocolRelativeHtmlLinks(html) {
-  const links = [];
-  for (const { href, line } of iterateHtmlAnchorHrefs(html)) {
-    if (!/^\/\//.test(href)) continue;
-    links.push({ href, line });
-  }
-  return links;
+  return classifyHtmlAnchorHrefs(html).protocolRelative;
 }
 
 export function extractHtmlIds(html) {
   const ids = [];
-  const regex = /<[A-Za-z][^>]*?\sid\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))[^>]*>/gi;
+  const regex = new RegExp(
+    `<[A-Za-z]${HTML_ATTRIBUTE_RUN}*?\\sid\\s*=\\s*${HTML_ATTRIBUTE_VALUE}${HTML_ATTRIBUTE_RUN}*>`,
+    "gi",
+  );
   let match;
   while ((match = regex.exec(html)) !== null) {
     ids.push(decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]));
@@ -636,7 +658,15 @@ function extractStaticMdxIds(body) {
     visibleLines.push(codeFenceOpener === null ? stripInlineCode(line) : "");
   }
   const elements = visibleLines.join("\n");
-  const regex = /<[A-Za-z][^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)')[^>]*>/gs;
+  // Same tokenising run as the built-HTML scans: a ">" inside a quoted MDX/JSX
+  // attribute value (title="a > b") must not truncate the tag and lose the id
+  // (#4048). The rest of this pattern keeps its own semantics — `\bid` also
+  // accepts `data-id`, and only non-empty quoted values count, unlike the
+  // built-HTML id scan.
+  const regex = new RegExp(
+    `<[A-Za-z]${HTML_ATTRIBUTE_RUN}*?\\bid\\s*=\\s*(?:"([^"]+)"|'([^']+)')${HTML_ATTRIBUTE_RUN}*>`,
+    "gs",
+  );
   let match;
   while ((match = regex.exec(elements)) !== null) ids.add(match[1] ?? match[2]);
   return ids;
@@ -743,6 +773,12 @@ export async function resolveLink(href, distDir, basePath = "/", fileDir = "") {
   return (await resolveDistTarget(href, distDir, basePath, fileDir)).type !== "missing";
 }
 
+/**
+ * Scan budget: exactly ONE anchor pass per page, and at most ONE id extraction
+ * per HTML target some fragment actually references. Ids are deliberately not
+ * extracted eagerly — most pages are never the target of a fragment link, and
+ * scanning them costs a full regex pass for a set nothing reads.
+ */
 export async function checkHtmlLinksAndTrailing(
   distDir,
   rootDir,
@@ -756,25 +792,25 @@ export async function checkHtmlLinksAndTrailing(
   const protocolRelative = [];
   const idCache = new Map();
   const cache = new Map();
-  const pages = [];
   const scanned = { links: 0, ids: 0 };
   for (const file of await collectFiles(distDir, [".html"])) {
     const content = await readFile(file, "utf-8");
-    const links = extractHtmlLinks(content);
-    const ids = extractHtmlIds(content);
+    const relFile = relative(rootDir, file);
+    // One anchor pass per page: internal links and the informational
+    // protocol-relative notices are disjoint buckets of the same match set.
+    const { links, protocolRelative: pageProtocolRelative } = classifyHtmlAnchorHrefs(content);
     scanned.links += links.length;
-    scanned.ids += ids.length;
-    idCache.set(file, new Set(ids));
-    pages.push({ file, links });
 
-    // Informational-only: classified from the content already in memory — no
-    // second read of the file.
-    const relFile = relative(rootDir, file);
-    for (const { href, line } of extractProtocolRelativeHtmlLinks(content)) {
+    // Filtered on the HREF, exactly like every other category below — an
+    // `excludePatterns` entry suppresses `//host/v/1.2/x` because the href
+    // matches, not because the page the href sits on is itself versioned.
+    // Without this the section had no off switch and consumers stopped
+    // reading it.
+    for (const { href, line } of pageProtocolRelative) {
+      if (excludePatterns.some((pattern) => pattern.test(href))) continue;
       protocolRelative.push({ file: relFile, line, href });
     }
-  }
-  for (const { file, links } of pages) {
+
     for (const { href, line } of links) {
       if (excludePatterns.some((pattern) => pattern.test(href))) continue;
       const cacheKey = href.startsWith("/") ? href : `${file}:${href}`;
@@ -783,13 +819,16 @@ export async function checkHtmlLinksAndTrailing(
         detail = await resolveDistTarget(href, distDir, basePath, dirname(file), file);
         cache.set(cacheKey, detail);
       }
-      if (detail.type === "missing") broken.push({ file: relative(rootDir, file), line, href });
+      if (detail.type === "missing") broken.push({ file: relFile, line, href });
       if (detail.fragment !== null) {
         let reason = detail.fragmentError;
         if (reason === null && detail.type !== "missing" && detail.targetFile !== null && extname(detail.targetFile) === ".html") {
           let ids = idCache.get(detail.targetFile);
           if (ids === undefined) {
-            const targetHtml = await readFile(detail.targetFile, "utf-8");
+            // The page being walked is already in memory; any other target is
+            // re-read here rather than retained, so the walk never holds more
+            // than one page's HTML no matter how large dist/ is.
+            const targetHtml = detail.targetFile === file ? content : await readFile(detail.targetFile, "utf-8");
             const targetIds = extractHtmlIds(targetHtml);
             scanned.ids += targetIds.length;
             ids = new Set(targetIds);
@@ -797,12 +836,12 @@ export async function checkHtmlLinksAndTrailing(
           }
           if (!ids.has(detail.fragment)) reason = "missing target id";
         }
-        if (reason !== null) anchors.push({ file: relative(rootDir, file), line, href, fragment: detail.fragment, reason });
+        if (reason !== null) anchors.push({ file: relFile, line, href, fragment: detail.fragment, reason });
       }
       if (checkTrailing) {
         const pathPart = href.split("#")[0].split("?")[0];
         if (pathPart && pathPart !== "/" && pathPart !== "." && pathPart !== "./" && !pathPart.endsWith("/") && !extname(pathPart) && detail.type === "directoryIndex") {
-          trailingSlash.push({ file: relative(rootDir, file), line, href });
+          trailingSlash.push({ file: relFile, line, href });
         }
       }
     }
@@ -914,9 +953,16 @@ async function main() {
   const realAbsolute = filter(mdxWarnings);
   const realAnchors = filter(anchorWarnings);
   const realTrailing = filter(trailingSlash);
-  console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings, protocolRelative));
+  // The one category filtered BEFORE printing. It has no strict gate, so the
+  // allowlist is a consumer's only way to quiet a known-good entry, and
+  // quieting has to reach the section and the count line alike or the section
+  // keeps nagging and stops being read.
+  const shownProtocolRelative = filter(protocolRelative);
+  console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings, shownProtocolRelative));
   if (hasDist) console.log(`\nBuilt HTML scan: ${scanned.links} internal link${scanned.links === 1 ? "" : "s"} and ${scanned.ids} ID attribute${scanned.ids === 1 ? "" : "s"} inspected.`);
-  if (protocolRelative.length > 0) console.log(`Protocol-relative links: ${protocolRelative.length} found (informational only — see "Protocol-Relative Links" section above; not counted as issues).`);
+  if (shownProtocolRelative.length > 0) console.log(`Protocol-relative links: ${shownProtocolRelative.length} found (informational only — see "Protocol-Relative Links" section above; not counted as issues).`);
+  // Protocol-relative suppressions are deliberately absent from this tally:
+  // the sentence is about strict-mode counts, and that category has none.
   const skipped = broken.length - realBroken.length + mdxWarnings.length - realAbsolute.length + anchorWarnings.length - realAnchors.length + trailingSlash.length - realTrailing.length;
   if (skipped > 0) console.log(`\nAllowlist: ${skipped} known exception${skipped === 1 ? "" : "s"} excluded from strict-mode counts (${allowlistPath}).`);
   let failed = false;

package/templates/base/scripts/setup-doc-skill.sh

@@ -190,7 +190,10 @@ REPO_ROOT="$(git -C "$ROOT_DIR" worktree list | head -1 | awk '{print $1}')"
 PROJECT_PREFIX="$(git -C "$ROOT_DIR" rev-parse --show-prefix)"
 MAIN_PROJECT_DIR="$REPO_ROOT/${PROJECT_PREFIX}"
 MAIN_PROJECT_DIR="${MAIN_PROJECT_DIR%/}"
-REPO_DOCS_DIR="$REPO_ROOT/${PROJECT_PREFIX}src/content/docs"
+# REPO_DOCS_DIR is set below, once the config parse resolves the real
+# (possibly custom) docsDir -- no hardcoded fallback is defined here so a
+# short-circuited parse fails loudly instead of silently reverting to
+# src/content/docs (#4047).
 
 # Read the current locale map from the project's config. The generated config
 # puts `defaultLocale`, `docsDir`, and `locales` directly in `zudoDoc({...})`.
@@ -200,7 +203,16 @@ REPO_DOCS_DIR="$REPO_ROOT/${PROJECT_PREFIX}src/content/docs"
 # This deliberately does NOT walk `src/content/docs-*`: that naming convention
 # also matches version snapshots such as `docs-v1-ja`, which are not current
 # locale roots. The config map is the only source of truth.
-CONFIG_LOCALE_DATA="$(node - "$ROOT_DIR" <<'NODE'
+#
+# The node call is wrapped in a function rather than inlined into the
+# assignment's `$( ... )`: bash 3.2 (stock macOS /bin/bash) does not honour a
+# heredoc opened inside a command substitution -- it scans the heredoc body as
+# shell text, and the JavaScript below contains an odd number of backticks
+# (template literals), so the whole FILE fails to parse. Keeping the heredoc at
+# statement level sidesteps that parser bug while preserving stdin execution,
+# argument indexing, and node's exit status through the assignment.
+read_config_locale_data() {
+  node - "$ROOT_DIR" <<'NODE'
 const fs = require("node:fs");
 const path = require("node:path");
 
@@ -445,7 +457,8 @@ if (localeObject) {
   }
 }
 NODE
-)"
+}
+CONFIG_LOCALE_DATA="$(read_config_locale_data)"
 
 DEFAULT_LOCALE="en"
 DOCS_DIR_REL="src/content/docs"
@@ -461,9 +474,13 @@ while IFS=$'\t' read -r record_type record_value record_extra; do
       [ -n "$record_value" ] || continue
       [ "$record_value" = "$DEFAULT_LOCALE" ] && continue
       duplicate="false"
-      for existing_code in "${LOCALE_CODES[@]}"; do
-        [ "$existing_code" = "$record_value" ] && duplicate="true"
-      done
+      # bash 3.2 under `set -u` treats "${arr[@]}" on an EMPTY array as an
+      # unbound variable, so the length guard is required, not cosmetic.
+      if [ "${#LOCALE_CODES[@]}" -gt 0 ]; then
+        for existing_code in "${LOCALE_CODES[@]}"; do
+          [ "$existing_code" = "$record_value" ] && duplicate="true"
+        done
+      fi
       [ "$duplicate" = "true" ] && continue
       LOCALE_CODES+=("$record_value")
       LOCALE_DIR_RELS+=("$record_extra")
@@ -578,12 +595,16 @@ locale_link_name() {
   suffix=2
   while :; do
     collision="false"
-    for existing in "${LOCALE_LINK_NAMES[@]}"; do
-      if [ "$existing" = "$name" ]; then
-        collision="true"
-        break
-      fi
-    done
+    # Length guard: see the LOCALE_CODES loop above -- bash 3.2 under `set -u`
+    # errors on "${arr[@]}" when the array is empty.
+    if [ "${#LOCALE_LINK_NAMES[@]}" -gt 0 ]; then
+      for existing in "${LOCALE_LINK_NAMES[@]}"; do
+        if [ "$existing" = "$name" ]; then
+          collision="true"
+          break
+        fi
+      done
+    fi
     [ "$collision" = "false" ] && break
     name="docs-$code-$suffix"
     suffix=$((suffix + 1))
@@ -606,13 +627,17 @@ locale_starter_note() {
   esac
 }
 
-# Build exact locale-map guidance for the generated skill. These lines come
-# only from configured `locales` entries, never from directory discovery.
+# Build exact locale-map guidance for the generated skill. Entries come from
+# configured `locales`, but only when the directory exists on disk -- gated
+# by the SAME existence check generate_skill uses below before symlinking,
+# so the guidance can never point at a locale link that was never created
+# (#4047).
 LOCALE_GUIDANCE="- \`$DEFAULT_LOCALE\` (default): \`${DOCS_DIR_REL%/}/\` — \`/docs/...\` ($(locale_starter_note "$DEFAULT_LOCALE"))"
 LOCALE_GUIDANCE+=$'\n'
 for locale_index in "${!LOCALE_CODES[@]}"; do
   locale_code="${LOCALE_CODES[$locale_index]}"
   locale_dir="${LOCALE_DIR_RELS[$locale_index]}"
+  [ -d "$ROOT_DIR/$locale_dir" ] || continue
   locale_link="${LOCALE_LINK_NAMES[$locale_index]}"
   locale_note="$(locale_starter_note "$locale_code")"
   LOCALE_GUIDANCE+="- \`$locale_code\`: \`${locale_dir%/}/\` — \`/$locale_code/docs/...\` (${locale_note}); lookup link: \`$locale_link/\`"
@@ -627,6 +652,10 @@ if [ "$DEFAULT_LOCALE" = "ja" ]; then
 else
   for locale_index in "${!LOCALE_CODES[@]}"; do
     if [ "${LOCALE_CODES[$locale_index]}" = "ja" ]; then
+      locale_dir="${LOCALE_DIR_RELS[$locale_index]}"
+      # Same existence check as the LOCALE_GUIDANCE loop above and
+      # generate_skill's symlink step below (#4047).
+      [ -d "$ROOT_DIR/$locale_dir" ] || break
       JA_DOCS_LINK="${LOCALE_LINK_NAMES[$locale_index]}"
       JA_DOCS_PATH="${LOCALE_DIR_RELS[$locale_index]}"
       break