@cosmicdrift/kumiko-cli 0.355.0 → 0.357.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.355.0",
-  "description": "CLI for Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` scaffolds a runnable workspace; `add feature <name>` mounts a feature; `check` runs boot validation plus the guard suites with the step list derived from kumiko.json; `agent lint`, `project` and `consumer` operate on an existing app.",
+  "version": "0.357.0",
+  "description": "CLI for Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` scaffolds a runnable workspace; `add feature <name>` mounts a feature; `check` runs boot validation plus the guard suites with the step list derived from kumiko.json; `agent lint`, `project` and `consumer` operate on an existing app; `handbuch build` renders the HTML handbuch.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -36,27 +36,38 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.355.0",
-    "@cosmicdrift/kumiko-guards": "0.355.0",
-    "@cosmicdrift/kumiko-repo-manifest": "0.355.0",
-    "@cosmicdrift/kumiko-testing": "0.355.0",
+    "@cosmicdrift/kumiko-dev-server": "0.357.0",
+    "@cosmicdrift/kumiko-guards": "0.357.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.357.0",
+    "@cosmicdrift/kumiko-testing": "0.357.0",
+    "marked": "^18.0.3",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
+    "sharp": "^0.35.5",
     "@cosmicdrift/kumiko-bundled-features": ">=0.353.0 <1.0.0",
-    "@cosmicdrift/kumiko-framework": ">=0.353.0 <1.0.0"
+    "@cosmicdrift/kumiko-framework": ">=0.353.0 <1.0.0",
+    "@cosmicdrift/kumiko-headless": ">=0.353.0 <1.0.0"
   },
   "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    },
     "@cosmicdrift/kumiko-bundled-features": {
       "optional": true
     },
     "@cosmicdrift/kumiko-framework": {
       "optional": true
+    },
+    "@cosmicdrift/kumiko-headless": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.355.0",
-    "@cosmicdrift/kumiko-framework": "0.355.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.357.0",
+    "@cosmicdrift/kumiko-framework": "0.357.0",
+    "@cosmicdrift/kumiko-headless": "0.357.0",
+    "sharp": "^0.35.5"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.357.0",
+    "type": "improvement",
+    "title": "kumiko handbuch build generates the user manual from a JSON config",
+    "detail": "New command `kumiko handbuch build` generates the user manual as a static page from a JSON config\n`kumiko handbuch build <config.json> [--root <dir>] [--out <dir>] [--shots <dir>] [--texts <dir>] [--web-shots <dir>] [--web-texts <dir>] [--web-repo <dir>] [--repo <dir>] [--locale <l>] [--no-large]`. Relative config paths resolve against `--root` (default: the working directory); the default output is `<root>/.handbuch/<config-name>`. Image conversion needs `sharp`, which is an optional peer dependency: without it the command prints an install hint and exits 1. The command also needs the app's `@cosmicdrift/kumiko-framework` and `@cosmicdrift/kumiko-headless` (optional peers, loaded only when `handbuch build` runs). Replaces the workspace handbuch builder script."
+  },
   {
     "version": "0.354.0",
     "type": "improvement",

package/src/commands/handbuch.ts

@@ -0,0 +1,123 @@
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { ZodError } from "zod";
+import type { HandbuchConfig } from "../handbuch/config";
+import type { CliCommand, CliCommandContext } from "./types";
+
+const USAGE =
+  "Usage: kumiko handbuch build <config.json> [--root <dir>] [--out <dir>] [--shots <dir>] [--texts <dir>] [--web-shots <dir>] [--web-texts <dir>] [--web-repo <dir>] [--repo <dir>] [--locale <l>] [--no-large]";
+
+const BUILD_OPTIONS = {
+  root: { type: "string" },
+  out: { type: "string" },
+  shots: { type: "string" },
+  texts: { type: "string" },
+  "web-shots": { type: "string" },
+  "web-texts": { type: "string" },
+  "web-repo": { type: "string" },
+  repo: { type: "string" },
+  locale: { type: "string" },
+  "no-large": { type: "boolean" },
+} as const;
+
+function usageError(ctx: CliCommandContext, message?: string): number {
+  ctx.out.err("");
+  if (message) ctx.out.err(`  ${message}`);
+  ctx.out.err(`  ${USAGE}`);
+  ctx.out.err("");
+  return 2;
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof ZodError) {
+    return error.issues
+      .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+      .join("\n  ");
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function appSlug(configPath: string): string {
+  return basename(configPath).replace(/\.json$/, "") || "handbuch";
+}
+
+async function runBuild(ctx: CliCommandContext, args: ReadonlyArray<string>): Promise<number> {
+  let parsed: ReturnType<
+    typeof parseArgs<{ options: typeof BUILD_OPTIONS; allowPositionals: true }>
+  >;
+  try {
+    parsed = parseArgs({ args: [...args], options: BUILD_OPTIONS, allowPositionals: true });
+  } catch (error) {
+    return usageError(ctx, describeError(error));
+  }
+  const { values, positionals } = parsed;
+  const configArg = positionals[0];
+  if (!configArg) return usageError(ctx, "Missing <config.json>.");
+
+  const rootDir = resolve(ctx.cwd, values.root ?? ".");
+  const configPath = resolve(rootDir, configArg);
+  // Lazy: the builder pulls in optional peers (framework, headless) that other commands must not need.
+  const { loadHandbuchConfig, restrictToLocale } = await import("../handbuch/config");
+  const { buildHandbuch, SHARP_MISSING_MESSAGE } = await import("../handbuch/build");
+  let config: HandbuchConfig;
+  try {
+    const loaded = loadHandbuchConfig(configPath);
+    const narrowed = values.locale ? restrictToLocale(loaded, values.locale) : loaded;
+    // Worktree checkouts hold the code the texts describe; the configured
+    // sibling checkouts may sit on another commit.
+    config = {
+      ...narrowed,
+      repo: values.repo ? resolve(ctx.cwd, values.repo) : narrowed.repo,
+      flowSources: narrowed.flowSources?.map((source) => ({
+        ...source,
+        repo: values["web-repo"] ? resolve(ctx.cwd, values["web-repo"]) : source.repo,
+      })),
+    };
+  } catch (error) {
+    ctx.out.err("");
+    ctx.out.err(`  Invalid handbuch config ${configPath}:`);
+    ctx.out.err(`  ${describeError(error)}`);
+    ctx.out.err(`  ${USAGE}`);
+    ctx.out.err("");
+    return 2;
+  }
+
+  const optionalDir = (value: string | undefined) => (value ? resolve(ctx.cwd, value) : undefined);
+  try {
+    const result = await buildHandbuch(config, {
+      rootDir,
+      outDir: resolve(ctx.cwd, values.out ?? join(rootDir, ".handbuch", appSlug(configPath))),
+      shotsDir: optionalDir(values.shots),
+      textsDir: optionalDir(values.texts),
+      flowShotsDir: optionalDir(values["web-shots"]),
+      flowTextsDir: optionalDir(values["web-texts"]),
+      withLarge: !values["no-large"],
+    });
+    const { stats } = result;
+    ctx.out.log(
+      `${config.title}: ${stats.chapters} Kapitel, ${stats.textMissing} Text fehlt, ${stats.imageMissing} Bild fehlt, ${stats.staleText} Text veraltet?, ${stats.planned} geplant`,
+    );
+    ctx.out.log(
+      `${result.outDir} (${result.imageCount} Bilder, ${(result.totalBytes / 1024 / 1024).toFixed(1)} MB)`,
+    );
+    return 0;
+  } catch (error) {
+    ctx.out.err("");
+    ctx.out.err(
+      `  ✗ ${error instanceof Error && error.message === SHARP_MISSING_MESSAGE ? error.message : describeError(error)}`,
+    );
+    ctx.out.err("");
+    return 1;
+  }
+}
+
+export const handbuchCommand: CliCommand = {
+  id: "handbuch",
+  description: "Build the HTML handbuch from a config (build <config.json>)",
+  help: `${USAGE}\n\nRenders the handbuch page from the texts and screenshots a config points at.\nRelative paths in the config resolve against --root (default: cwd); the output\ngoes to <root>/.handbuch/<config-name> unless --out is given. Needs sharp\n(bun add -d sharp) for the image conversion.`,
+  run: async (ctx) => {
+    const [sub, ...rest] = ctx.argv;
+    if (sub !== "build") return usageError(ctx);
+    return runBuild(ctx, rest);
+  },
+};

package/src/commands/index.ts

@@ -1,6 +1,7 @@
 import { agentCommand } from "./agent";
 import { checkCommand } from "./check";
 import { consumerCommand } from "./consumer";
+import { handbuchCommand } from "./handbuch";
 import { projectCommand } from "./project";
 import type { CliCommand } from "./types";
 
@@ -9,6 +10,7 @@ export const APP_COMMANDS: ReadonlyArray<CliCommand> = [
   agentCommand,
   projectCommand,
   consumerCommand,
+  handbuchCommand,
 ];
 
 export function findAppCommand(id: string): CliCommand | undefined {
@@ -23,4 +25,4 @@ export {
   runCheck,
 } from "./check";
 export type { CliCommand, CliCommandContext } from "./types";
-export { agentCommand, checkCommand, consumerCommand, projectCommand };
+export { agentCommand, checkCommand, consumerCommand, handbuchCommand, projectCommand };

package/src/handbuch/build.ts

@@ -0,0 +1,102 @@
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { collectBuildInfo, type WallClock } from "./buildinfo";
+import type { HandbuchConfig } from "./config";
+import { buildModel, type Model } from "./model";
+import { createImagePlan, type ImagePlan, renderPage } from "./render";
+
+const CONVERSION_BATCH = 8;
+
+export type BuildResult = {
+  outDir: string;
+  stats: Model["stats"];
+  imageCount: number;
+  totalBytes: number;
+};
+
+type Sharp = typeof import("sharp").default;
+
+export const SHARP_MISSING_MESSAGE =
+  "sharp is not installed. Install it to build the handbuch (bun add -d sharp).";
+
+// sharp is native and an optional peer: only the build path may load it.
+async function loadSharp(): Promise<Sharp> {
+  try {
+    return (await import("sharp")).default;
+  } catch {
+    throw new Error(SHARP_MISSING_MESSAGE);
+  }
+}
+
+async function convertImages(sharp: Sharp, outDir: string, images: ImagePlan): Promise<void> {
+  const jobs = [...images.jobs];
+  for (let start = 0; start < jobs.length; start += CONVERSION_BATCH) {
+    await Promise.all(
+      jobs.slice(start, start + CONVERSION_BATCH).map(async ([dest, job]) => {
+        const target = join(outDir, dest);
+        mkdirSync(dirname(target), { recursive: true });
+        await sharp(job.src)
+          .flatten({ background: "#ffffff" })
+          .resize({ width: job.width, withoutEnlargement: true })
+          .webp({ quality: job.quality })
+          .toFile(target);
+      }),
+    );
+  }
+}
+
+function directorySize(dir: string): number {
+  let total = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    total += entry.isDirectory() ? directorySize(path) : statSync(path).size;
+  }
+  return total;
+}
+
+export async function buildHandbuch(
+  config: HandbuchConfig,
+  options: {
+    rootDir: string;
+    outDir: string;
+    shotsDir?: string;
+    textsDir?: string;
+    flowShotsDir?: string;
+    flowTextsDir?: string;
+    withLarge?: boolean;
+    now?: WallClock;
+  },
+): Promise<BuildResult> {
+  const sharp = await loadSharp();
+  const model = await buildModel(config, {
+    rootDir: options.rootDir,
+    shotsDir: options.shotsDir,
+    textsDir: options.textsDir,
+    flowShotsDir: options.flowShotsDir,
+    flowTextsDir: options.flowTextsDir,
+  });
+  const images = createImagePlan(options.withLarge ?? true);
+  const html = renderPage(
+    config.translations?.[config.defaultLocale]?.title ?? config.title,
+    model,
+    images,
+    collectBuildInfo(
+      resolve(options.rootDir, config.repo),
+      options.now,
+      (config.flowSources ?? []).map((source) => resolve(options.rootDir, source.repo)),
+      config.defaultLocale,
+    ),
+  );
+
+  rmSync(options.outDir, { recursive: true, force: true });
+  mkdirSync(options.outDir, { recursive: true });
+  await convertImages(sharp, options.outDir, images);
+  writeFileSync(join(options.outDir, "index.html"), html);
+
+  return {
+    outDir: options.outDir,
+    stats: model.stats,
+    imageCount: images.jobs.size,
+    totalBytes: directorySize(options.outDir),
+  };
+}

package/src/handbuch/buildinfo.ts

@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+const FRAMEWORK_PACKAGE = "@cosmicdrift/kumiko-framework";
+
+export type BuildInfo = {
+  appVersion?: string;
+  frameworkVersion?: string;
+  frameworkPin?: string;
+  git?: { sha: string; branch: string };
+  sourceVersions: Array<{ name: string; version: string }>;
+  builtAt: string;
+};
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" && parsed !== null
+      ? Object.fromEntries(Object.entries(parsed))
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringField(record: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function resolvedFrameworkVersion(repoDir: string): string | undefined {
+  try {
+    const manifest = Bun.resolveSync(`${FRAMEWORK_PACKAGE}/package.json`, repoDir);
+    return stringField(readJson(manifest), "version");
+  } catch {
+    return undefined;
+  }
+}
+
+function gitOutput(repoDir: string, args: string[]): string | undefined {
+  try {
+    const text = execFileSync("git", ["-C", repoDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return text || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export type WallClock = { year: number; month: number; day: number; hour: number; minute: number };
+
+export function currentWallClock(): WallClock {
+  const { year, month, day, hour, minute } = Temporal.Now.zonedDateTimeISO();
+  return { year, month, day, hour, minute };
+}
+
+const pad2 = (value: number) => String(value).padStart(2, "0");
+
+export function formatGermanDateTime(at: WallClock): string {
+  return `${pad2(at.day)}.${pad2(at.month)}.${at.year}, ${pad2(at.hour)}:${pad2(at.minute)}`;
+}
+
+export function formatIsoDateTime(at: WallClock): string {
+  return `${at.year}-${pad2(at.month)}-${pad2(at.day)} ${pad2(at.hour)}:${pad2(at.minute)}`;
+}
+
+export function collectBuildInfo(
+  repoDir: string,
+  now: WallClock = currentWallClock(),
+  extraRepoDirs: readonly string[] = [],
+  locale = "de",
+): BuildInfo {
+  const manifest = readJson(join(repoDir, "package.json"));
+  const dependencies = manifest?.["dependencies"];
+  const declared =
+    typeof dependencies === "object" && dependencies !== null
+      ? Object.entries(dependencies).find(([name]) => name === FRAMEWORK_PACKAGE)?.[1]
+      : undefined;
+  const frameworkVersion = resolvedFrameworkVersion(repoDir);
+  const pin = typeof declared === "string" ? declared : undefined;
+  const sha = gitOutput(repoDir, ["rev-parse", "--short", "HEAD"]);
+  const branch = gitOutput(repoDir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  return {
+    appVersion: stringField(manifest, "version"),
+    frameworkVersion,
+    frameworkPin: pin && pin !== frameworkVersion ? pin : undefined,
+    git: sha && branch ? { sha, branch } : undefined,
+    sourceVersions: extraRepoDirs.flatMap((dir) => {
+      const version = stringField(readJson(join(dir, "package.json")), "version");
+      return version ? [{ name: basename(dir), version }] : [];
+    }),
+    builtAt: locale === "de" ? formatGermanDateTime(now) : formatIsoDateTime(now),
+  };
+}
+
+export function buildInfoLines(info: BuildInfo, builtLabel = "Stand"): string[] {
+  const lines: string[] = [];
+  if (info.appVersion) lines.push(`App ${info.appVersion}`);
+  if (info.frameworkVersion) {
+    lines.push(
+      `Kumiko ${info.frameworkVersion}${info.frameworkPin ? ` (Pin ${info.frameworkPin})` : ""}`,
+    );
+  }
+  if (info.git) lines.push(`${info.git.branch} @ ${info.git.sha}`);
+  for (const source of info.sourceVersions) lines.push(`${source.name} ${source.version}`);
+  lines.push(`${builtLabel} ${info.builtAt}`);
+  return lines;
+}

package/src/handbuch/chrome.ts

@@ -0,0 +1,96 @@
+export type Chrome = {
+  imageMissing: string;
+  textMissing: string;
+  textMissingBody: string;
+  textStale: string;
+  staleBody: string;
+  textFallbackNotice: (fallbackLocale: string) => string;
+  shotsFallbackNotice: (shotsLocale: string) => string;
+  chapters: string;
+  overview: string;
+  planned: string;
+  plannedShort: string;
+  staleShort: string;
+  plannedIntro: string;
+  plannedNone: string;
+  plannedColumns: [string, string, string];
+  appendix: string;
+  language: string;
+  size: string;
+  hint: string;
+  lightbox: string;
+  close: string;
+  fallbackGroup: string;
+  builtAt: string;
+  viewports: { desktop: string; tablet: string; mobile: string; all: string };
+};
+
+const de: Chrome = {
+  imageMissing: "Bild fehlt",
+  textMissing: "Text fehlt",
+  textMissingBody: "Für dieses Kapitel gibt es noch keinen Text.",
+  textStale: "Text veraltet?",
+  staleBody: "Diese fett gesetzten Begriffe stehen nicht in den Oberflächentexten:",
+  textFallbackNotice: (locale) => `Text in dieser Sprache fehlt, angezeigt wird ${locale}.`,
+  shotsFallbackNotice: (locale) => `Screenshots nur in ${locale} vorhanden.`,
+  chapters: "Kapitel",
+  overview: "Übersicht",
+  planned: "Geplante Masken",
+  plannedShort: "geplant",
+  staleShort: "veraltet?",
+  plannedIntro: "Diese Masken stehen in der Screen-Liste, haben aber weder Text noch Screenshots.",
+  plannedNone: "Alle Masken sind dokumentiert.",
+  plannedColumns: ["Maske", "Kennung", "Gruppe"],
+  appendix: "Anhang",
+  language: "Sprache",
+  size: "Größe",
+  hint: "↑ ↓ Kapitel · 1 2 3 4 Größe",
+  lightbox: "Screenshot vergrößert",
+  close: "Schließen",
+  fallbackGroup: "Weitere",
+  builtAt: "Stand",
+  viewports: {
+    desktop: "Desktop",
+    tablet: "Tablet",
+    mobile: "Mobil",
+    all: "Alle",
+  },
+};
+
+const en: Chrome = {
+  imageMissing: "Image missing",
+  textMissing: "Text missing",
+  textMissingBody: "This chapter has no text yet.",
+  textStale: "Text outdated?",
+  staleBody: "These bold terms do not appear in the UI strings:",
+  textFallbackNotice: (locale) => `Text missing in this language, showing ${locale}.`,
+  shotsFallbackNotice: (locale) => `Screenshots only available in ${locale}.`,
+  chapters: "Chapters",
+  overview: "Overview",
+  planned: "Planned screens",
+  plannedShort: "planned",
+  staleShort: "outdated?",
+  plannedIntro: "These screens are in the screen list but have neither text nor screenshots.",
+  plannedNone: "All screens are documented.",
+  plannedColumns: ["Screen", "ID", "Group"],
+  appendix: "Appendix",
+  language: "Language",
+  size: "Size",
+  hint: "↑ ↓ Chapter · 1 2 3 4 Size",
+  lightbox: "Screenshot enlarged",
+  close: "Close",
+  fallbackGroup: "Other",
+  builtAt: "Built",
+  viewports: {
+    desktop: "Desktop",
+    tablet: "Tablet",
+    mobile: "Mobile",
+    all: "All",
+  },
+};
+
+const CHROME: Record<string, Chrome> = { de, en };
+
+export function chromeFor(locale: string): Chrome {
+  return CHROME[locale] ?? de;
+}

package/src/handbuch/config.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+
+const screensModuleSchema = z.object({
+  path: z.string().min(1),
+  export: z.string().min(1),
+  idKey: z.string().min(1),
+  titleKey: z.string().min(1),
+  groupKey: z.string().min(1),
+});
+
+const inlineScreenSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().optional(),
+  group: z.string().min(1),
+});
+
+const flowSourceSchema = z.object({
+  repo: z.string().min(1),
+  textsDir: z.string().includes("{locale}"),
+  pageFlows: z.array(z.string().min(1)).default([]),
+  pageGroup: z.object({ id: z.string().min(1), label: z.string().min(1) }),
+  flowGroup: z.object({ id: z.string().min(1), label: z.string().min(1) }),
+  flowTitles: z.record(z.string(), z.string()).default({}),
+  shotsDir: z.string().optional(),
+  uiStringsByLocale: z.record(z.string(), z.array(z.string().min(1))).optional(),
+  uiStringFiles: z.array(z.string().min(1)).optional(),
+});
+
+const groupSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+});
+
+// Labels for the build locale; ids without an entry keep their base label.
+const translationsSchema = z.object({
+  title: z.string().min(1).optional(),
+  groups: z.record(z.string(), z.string()).default({}),
+  flows: z.record(z.string(), z.string()).default({}),
+  steps: z.record(z.string(), z.string()).default({}),
+});
+
+export const handbuchConfigSchema = z
+  .object({
+    title: z.string().min(1),
+    repo: z.string().min(1),
+    locales: z.array(z.string().min(1)).min(1),
+    defaultLocale: z.string().min(1),
+    groups: z.array(groupSchema).min(1),
+    translations: z.record(z.string(), translationsSchema).optional(),
+    textsDir: z.string().includes("{locale}"),
+    shotsDir: z.string().optional(),
+    uiStrings: z.array(z.string().min(1)).optional(),
+    uiStringPackages: z
+      .array(
+        z.object({
+          package: z.string().min(1),
+          files: z.array(z.string().min(1)).min(1),
+          locale: z.string().min(1).optional(),
+        }),
+      )
+      .optional(),
+    flowSources: z.array(flowSourceSchema).optional(),
+    sort: z.enum(["source", "title"]).default("source"),
+    screensModule: screensModuleSchema.optional(),
+    screens: z.array(inlineScreenSchema).optional(),
+  })
+  .refine((config) => config.locales.includes(config.defaultLocale), {
+    message: "defaultLocale must be one of locales",
+    path: ["defaultLocale"],
+  })
+  .refine((config) => !(config.screensModule && config.screens), {
+    message: "use either screensModule or screens, not both",
+    path: ["screens"],
+  });
+
+export type HandbuchConfig = z.infer<typeof handbuchConfigSchema>;
+export type FlowSourceConfig = z.infer<typeof flowSourceSchema>;
+export type ScreensModuleConfig = z.infer<typeof screensModuleSchema>;
+
+export function parseHandbuchConfig(raw: unknown): HandbuchConfig {
+  return handbuchConfigSchema.parse(raw);
+}
+
+export function loadHandbuchConfig(configPath: string): HandbuchConfig {
+  const raw = parseJsonOrThrow<unknown>(readFileSync(configPath, "utf8"), configPath);
+  return parseHandbuchConfig(raw);
+}
+
+// One build per language keeps the artifact under its file limit.
+export function restrictToLocale(config: HandbuchConfig, locale: string): HandbuchConfig {
+  if (!config.locales.includes(locale)) {
+    throw new Error(`--locale ${locale} is not one of ${config.locales.join(", ")}`);
+  }
+  return { ...config, locales: [locale], defaultLocale: locale };
+}