@takazudo/zudo-doc 5.18.2 → 5.19.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@takazudo/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
+
+### Bug Fixes
+
+- The `gen-z-index` and `gen-component-tokens` bins report a descriptive error instead of a raw Node stack trace. A missing input file now names the path and says which file it is, while `EACCES` / `EISDIR` keep their own message rather than collapsing into a misleading "not found", and a top-level handler prints the message to stderr and exits 1 for any deliberate throw. A non-`Error` throw prints its string form rather than a bare `undefined`. (83a4c6f7a, 134248eba)
+
 ## [5.18.2] - 2026-09-06
 
 ### Bug Fixes

package/bin/gen-component-tokens.mjs

@@ -45,6 +45,11 @@ const TOKENS_PATH = resolve(PKG_ROOT, "src/config/component-tokens.ts");
 const CONTENT_CSS_PATH = resolve(PKG_ROOT, "src/content.css");
 const FEATURES_CSS_PATH = resolve(PKG_ROOT, "src/features.css");
 
+// Repo-relative label for TOKENS_PATH, matching the SURFACES table's relPath
+// convention below — used only in the missing-file message so it never
+// embeds this machine's absolute path.
+const TOKENS_REL_PATH = "packages/zudo-doc/src/config/component-tokens.ts";
+
 // Default marker pair = the content-surface block. Kept under the original
 // names so buildBlock/replaceBlock default to the content block, preserving the
 // byte-identical content.css output (and the existing unit-test call sites).
@@ -259,10 +264,30 @@ export function replaceBlock(
   return css.slice(0, lineStart) + block + css.slice(lineEnd);
 }
 
+/**
+ * Reads a package-owned file, translating a missing file into a message that
+ * names both which file (`label`) and its repo-relative path (`relPath`) —
+ * these paths are absolute constants (see TOKENS_PATH/SURFACES above), so the
+ * relative label is what keeps the message free of a machine-specific path.
+ * Only ENOENT is translated: EACCES/EISDIR etc. are real, distinct failures
+ * (a permissions problem or "that's a directory") that a "not found" message
+ * would misreport, so they propagate unchanged with Node's own message.
+ */
+function readNamedFile(absPath, relPath, label) {
+  try {
+    return readFileSync(absPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`${label} file not found at ${relPath}`);
+    }
+    throw error;
+  }
+}
+
 function main() {
   const check = process.argv.includes("--check");
 
-  const tokensSrc = readFileSync(TOKENS_PATH, "utf8");
+  const tokensSrc = readNamedFile(TOKENS_PATH, TOKENS_REL_PATH, "tokens");
   const tokens = parseTokens(tokensSrc);
   const routes = routeBySurface(tokens);
 
@@ -277,7 +302,7 @@ function main() {
       `${target.surface}: ${surfaceTokens.length} token(s), ${selectorCount} selector(s)`,
     );
 
-    const css = readFileSync(target.cssPath, "utf8");
+    const css = readNamedFile(target.cssPath, target.relPath, "css");
     const block = buildBlock(surfaceTokens, target.beginMarker, target.endMarker);
     const next = replaceBlock(
       css,
@@ -344,5 +369,21 @@ function isDirectInvocation() {
 }
 
 if (isDirectInvocation()) {
-  process.exit(main());
+  // Turns any Error thrown by main() (the readNamedFile guard, the parser's
+  // loud-failure throws, or replaceBlock's missing-markers throw) into a
+  // single readable stderr line instead of a raw Node stack trace. This also
+  // hides the stack for a genuine *programming* error, not just a user-input
+  // one — an accepted CLI tradeoff, not an accident: the process still exits
+  // 1 and nothing is swallowed, but a future reader debugging an internal
+  // crash needs to call the exported `main()` directly (or temporarily
+  // remove this try/catch) to see the stack. Exit codes are unchanged:
+  // main()'s own return value (0 or 1) still flows through process.exit on
+  // the success path; only an uncaught throw is newly turned into exit(1)
+  // with a message.
+  try {
+    process.exit(main());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
 }

package/bin/gen-z-index.mjs

@@ -1023,6 +1023,26 @@ export function buildMdTable(tiers, options = {}) {
   return lines.join("\n");
 }
 
+/**
+ * Reads a user-supplied file, translating a missing file into a message that
+ * names both which file (`label`) and where it looked (`asGivenPath` — the
+ * as-given path, never the resolved absolute one, matching the convention
+ * documented on `main()` below). Only ENOENT is translated: EACCES/EISDIR
+ * etc. are real, distinct failures (a permissions problem or "that's a
+ * directory") that a "not found" message would misreport, so they propagate
+ * unchanged with Node's own message.
+ */
+function readNamedFile(absPath, asGivenPath, label) {
+  try {
+    return readFileSync(absPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`${label} file not found at ${asGivenPath}`);
+    }
+    throw error;
+  }
+}
+
 /**
  * CLI entrypoint. `argv` defaults to the real process argv (minus the node/
  * script prefix) so `isDirectInvocation()` below can call `main()` with no
@@ -1052,8 +1072,8 @@ export function main(argv = process.argv.slice(2)) {
   const tokensAbsPath = resolve(root, tokensPath);
   const cssAbsPath = resolve(root, cssPath);
 
-  const tokensSrc = readFileSync(tokensAbsPath, "utf8");
-  const css = readFileSync(cssAbsPath, "utf8");
+  const tokensSrc = readNamedFile(tokensAbsPath, tokensPath, "tokens");
+  const css = readNamedFile(cssAbsPath, cssPath, "css");
 
   const tiers = parseTiers(tokensSrc, tokensPath);
   const block = buildBlock(tiers, { tokensPath, cssPath, themeWrapper });
@@ -1064,7 +1084,7 @@ export function main(argv = process.argv.slice(2)) {
   let nextMd;
   if (mdTablePath !== undefined) {
     mdAbsPath = resolve(root, mdTablePath);
-    mdSrc = readFileSync(mdAbsPath, "utf8");
+    mdSrc = readNamedFile(mdAbsPath, mdTablePath, "md-table");
     const mdBlock = buildMdTable(tiers, { tokensPath });
     nextMd = replaceBlock(
       mdSrc,
@@ -1141,5 +1161,20 @@ function isDirectInvocation() {
 }
 
 if (isDirectInvocation()) {
-  process.exit(main());
+  // Turns any Error thrown by main() (there are ~17 deliberate `throw new
+  // Error(...)` call sites above, plus the readNamedFile guard) into a single
+  // readable stderr line instead of a raw Node stack trace. This also hides
+  // the stack for a genuine *programming* error, not just a user-input one —
+  // an accepted CLI tradeoff, not an accident: the process still exits 1 and
+  // nothing is swallowed, but a future reader debugging an internal crash
+  // needs to call the exported `main()` directly (or temporarily remove this
+  // try/catch) to see the stack. Exit codes are unchanged: main()'s own
+  // return value (0 or 1) still flows through process.exit on the success
+  // path; only an uncaught throw is newly turned into exit(1) with a message.
+  try {
+    process.exit(main());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.18.2",
+  "version": "5.19.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -720,7 +720,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.18.2"
+    "@takazudo/zudo-doc-history-server": "5.19.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",