@cosmicdrift/kumiko-cli 0.415.0 → 0.416.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.415.0",
+  "version": "0.416.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,19 +36,19 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.415.0",
-    "@cosmicdrift/kumiko-feature-ast": "0.415.0",
-    "@cosmicdrift/kumiko-guards": "0.415.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.415.0",
-    "@cosmicdrift/kumiko-testing": "0.415.0",
+    "@cosmicdrift/kumiko-dev-server": "0.416.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.416.0",
+    "@cosmicdrift/kumiko-guards": "0.416.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.416.0",
+    "@cosmicdrift/kumiko-testing": "0.416.0",
     "marked": "^18.1.2",
     "zod": "^4.6.7"
   },
   "peerDependencies": {
     "sharp": "^0.35.5",
-    "@cosmicdrift/kumiko-bundled-features": "0.415.0",
-    "@cosmicdrift/kumiko-framework": "0.415.0",
-    "@cosmicdrift/kumiko-renderer": "0.415.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.416.0",
+    "@cosmicdrift/kumiko-framework": "0.416.0",
+    "@cosmicdrift/kumiko-renderer": "0.416.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -65,9 +65,9 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.415.0",
-    "@cosmicdrift/kumiko-framework": "0.415.0",
-    "@cosmicdrift/kumiko-renderer": "0.415.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.416.0",
+    "@cosmicdrift/kumiko-framework": "0.416.0",
+    "@cosmicdrift/kumiko-renderer": "0.416.0",
     "sharp": "^0.35.5"
   },
   "publishConfig": {

package/src/commands/handbuch.ts

@@ -20,10 +20,23 @@ const BUILD_OPTIONS = {
   "no-large": { type: "boolean" },
 } as const;
 
-function usageError(ctx: CliCommandContext, message?: string): number {
+const KNOWLEDGE_USAGE =
+  "Usage: kumiko handbuch knowledge <config.json> --out <file.json> [--root <dir>] [--texts <dir>] [--web-texts <dir>] [--web-repo <dir>] [--repo <dir>] [--locale <l>]";
+
+const KNOWLEDGE_OPTIONS = {
+  root: { type: "string" },
+  out: { type: "string" },
+  texts: { type: "string" },
+  "web-texts": { type: "string" },
+  "web-repo": { type: "string" },
+  repo: { type: "string" },
+  locale: { type: "string" },
+} as const;
+
+function usageError(ctx: CliCommandContext, message?: string, usage: string = USAGE): number {
   ctx.out.err("");
   if (message) ctx.out.err(`  ${message}`);
-  ctx.out.err(`  ${USAGE}`);
+  ctx.out.err(`  ${usage}`);
   ctx.out.err("");
   return 2;
 }
@@ -73,31 +86,23 @@ function wipesBuildInputs({
   return wipesProtectedDir || lieInsideSource;
 }
 
-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>.");
+type ConfigOverrides = { locale?: string; repo?: string; "web-repo"?: string };
 
-  const rootDir = resolve(ctx.cwd, values.root ?? ".");
-  const configPath = resolve(rootDir, configArg);
+// Reports a bad config itself; the caller only maps undefined to exit code 2.
+async function loadConfigWithOverrides(
+  ctx: CliCommandContext,
+  configPath: string,
+  values: ConfigOverrides,
+  usage: string,
+): Promise<HandbuchConfig | undefined> {
   // 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 = {
+    return {
       ...narrowed,
       repo: values.repo ? resolve(ctx.cwd, values.repo) : narrowed.repo,
       flowSources: narrowed.flowSources?.map((source) => ({
@@ -109,10 +114,71 @@ async function runBuild(ctx: CliCommandContext, args: ReadonlyArray<string>): Pr
     ctx.out.err("");
     ctx.out.err(`  Invalid handbuch config ${configPath}:`);
     ctx.out.err(`  ${describeError(error)}`);
-    ctx.out.err(`  ${USAGE}`);
+    ctx.out.err(`  ${usage}`);
     ctx.out.err("");
-    return 2;
+    return undefined;
   }
+}
+
+async function runKnowledge(ctx: CliCommandContext, args: ReadonlyArray<string>): Promise<number> {
+  let parsed: ReturnType<
+    typeof parseArgs<{ options: typeof KNOWLEDGE_OPTIONS; allowPositionals: true }>
+  >;
+  try {
+    parsed = parseArgs({ args: [...args], options: KNOWLEDGE_OPTIONS, allowPositionals: true });
+  } catch (error) {
+    return usageError(ctx, describeError(error), KNOWLEDGE_USAGE);
+  }
+  const { values, positionals } = parsed;
+  const configArg = positionals[0];
+  if (!configArg) return usageError(ctx, "Missing <config.json>.", KNOWLEDGE_USAGE);
+  if (!values.out) return usageError(ctx, "Missing --out <file>.", KNOWLEDGE_USAGE);
+
+  const rootDir = resolve(ctx.cwd, values.root ?? ".");
+  const configPath = resolve(rootDir, configArg);
+  const config = await loadConfigWithOverrides(ctx, configPath, values, KNOWLEDGE_USAGE);
+  if (!config) return 2;
+
+  const { writeKnowledge } = await import("../handbuch/knowledge");
+  try {
+    const result = await writeKnowledge(config, {
+      rootDir,
+      outFile: resolve(ctx.cwd, values.out),
+      textsDir: values.texts ? resolve(ctx.cwd, values.texts) : undefined,
+      flowTextsDir: values["web-texts"] ? resolve(ctx.cwd, values["web-texts"]) : undefined,
+    });
+    const counts = Object.entries(result.pageCounts)
+      .map(([locale, count]) => `${locale} ${count}`)
+      .join(", ");
+    ctx.out.log(`${config.title}: ${counts} Seiten`);
+    ctx.out.log(result.outFile);
+    return 0;
+  } catch (error) {
+    ctx.out.err("");
+    ctx.out.err(`  ✗ ${describeError(error)}`);
+    ctx.out.err("");
+    return 1;
+  }
+}
+
+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);
+  const { SHARP_MISSING_MESSAGE, buildHandbuch } = await import("../handbuch/build");
+  const config = await loadConfigWithOverrides(ctx, configPath, values, USAGE);
+  if (!config) return 2;
 
   // buildHandbuch wipes outDir recursively, so a mistyped --out must never be
   // (or contain) a directory the build reads from or the user works in.
@@ -162,10 +228,12 @@ async function runBuild(ctx: CliCommandContext, args: ReadonlyArray<string>): Pr
 
 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.`,
+  description:
+    "Build the HTML handbuch (build <config.json>) or export its texts as JSON (knowledge <config.json>)",
+  help: `${USAGE}\n${KNOWLEDGE_USAGE}\n\nknowledge writes the page texts per locale (without images) as deterministic JSON for the assistant.\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 === "knowledge") return runKnowledge(ctx, rest);
     if (sub !== "build") return usageError(ctx);
     return runBuild(ctx, rest);
   },

package/src/handbuch/chrome.ts

@@ -21,6 +21,7 @@ export type Chrome = {
   lightbox: string;
   close: string;
   fallbackGroup: string;
+  processGroup: string;
   builtAt: string;
   viewports: { desktop: string; tablet: string; mobile: string; all: string };
 };
@@ -48,6 +49,7 @@ const de: Chrome = {
   lightbox: "Screenshot vergrößert",
   close: "Schließen",
   fallbackGroup: "Weitere",
+  processGroup: "Aufgaben",
   builtAt: "Stand",
   viewports: {
     desktop: "Desktop",
@@ -80,6 +82,7 @@ const en: Chrome = {
   lightbox: "Screenshot enlarged",
   close: "Close",
   fallbackGroup: "Other",
+  processGroup: "Tasks",
   builtAt: "Built",
   viewports: {
     desktop: "Desktop",

package/src/handbuch/config.ts

@@ -50,6 +50,7 @@ export const handbuchConfigSchema = z
     groups: z.array(groupSchema).min(1),
     translations: z.record(z.string(), translationsSchema).optional(),
     textsDir: z.string().includes("{locale}"),
+    processTextsDir: z.string().includes("{locale}").optional(),
     shotsDir: z.string().optional(),
     uiStrings: z.array(z.string().min(1)).optional(),
     uiStringPackages: z

package/src/handbuch/knowledge.ts

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { HandbuchConfig } from "./config";
+import { type BuildModelOptions, buildModel, type Chapter, type Model } from "./model";
+
+export type KnowledgePageKind = "process" | "screen";
+
+export type KnowledgePage = {
+  id: string;
+  kind: KnowledgePageKind;
+  title: string;
+  questions: string[];
+  screens: string[];
+  start?: string;
+  bodyMd: string;
+};
+
+export type KnowledgeFile = {
+  defaultLocale: string;
+  locales: Record<string, KnowledgePage[]>;
+};
+
+const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
+
+export function stripMarkdownImages(bodyMd: string): string {
+  return bodyMd
+    .replace(MARKDOWN_IMAGE, "")
+    .replace(/[ \t]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function compareText(a: string, b: string): number {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}
+
+function pageOf(chapter: Chapter, locale: string): KnowledgePage | undefined {
+  const text = chapter.texts.get(locale);
+  if (!text) return undefined;
+  const kind: KnowledgePageKind = chapter.isProcess ? "process" : "screen";
+  return {
+    id: chapter.id,
+    kind,
+    title: text.title,
+    questions: text.questions,
+    screens: kind === "process" ? text.screens : [chapter.id],
+    ...(kind === "process" && text.start !== undefined && { start: text.start }),
+    bodyMd: stripMarkdownImages(text.bodyMd),
+  };
+}
+
+function comparePages(a: KnowledgePage, b: KnowledgePage): number {
+  return compareText(a.kind, b.kind) || compareText(a.id, b.id);
+}
+
+export function buildKnowledge(model: Model): KnowledgeFile {
+  const chapters = model.groups.flatMap((group) => group.chapters);
+  const locales: Record<string, KnowledgePage[]> = {};
+  for (const locale of [...model.locales].sort(compareText)) {
+    locales[locale] = chapters
+      .flatMap((chapter) => pageOf(chapter, locale) ?? [])
+      .sort(comparePages);
+  }
+  return { defaultLocale: model.defaultLocale, locales };
+}
+
+export async function writeKnowledge(
+  config: HandbuchConfig,
+  options: BuildModelOptions & { outFile: string },
+): Promise<{ outFile: string; pageCounts: Record<string, number> }> {
+  const { outFile, ...modelOptions } = options;
+  const knowledge = buildKnowledge(await buildModel(config, modelOptions));
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, `${JSON.stringify(knowledge, null, 2)}\n`);
+  return {
+    outFile,
+    pageCounts: Object.fromEntries(
+      Object.entries(knowledge.locales).map(([locale, pages]) => [locale, pages.length]),
+    ),
+  };
+}

package/src/handbuch/model.ts

@@ -22,6 +22,8 @@ export const VIEWPORT_WIDTH: Record<Viewport, number> = {
 };
 
 const FALLBACK_GROUP_ID = "weitere";
+const PROCESS_GROUP_ID = "aufgaben";
+const PROCESS_ID_PREFIX = "prozess-";
 
 const LIGHT_THEME_DIR = "default-light";
 const LOCAL_IMAGE_REF = /\.(png|jpe?g|webp|gif|svg)$/i;
@@ -35,7 +37,10 @@ export type LocaleText = {
   bodyMd: string;
   dir: string;
   gruppe?: string;
+  start?: string;
   prozesse: string[];
+  questions: string[];
+  screens: string[];
   missingImages: string[];
   uiIgnore: string[];
   staleTerms: string[];
@@ -56,6 +61,7 @@ export type Chapter = {
   matrix: Map<string, MatrixShots>;
   steps?: Step[];
   inScreenList: boolean;
+  isProcess?: boolean;
 };
 
 export type Model = {
@@ -134,6 +140,24 @@ export function parseList(raw: string | undefined): string[] {
     .filter(Boolean);
 }
 
+// Inline `key: [a, b]` or a YAML block list; parseFrontmatter only keeps single-line values.
+export function parseFrontmatterList(raw: string, key: string): string[] {
+  const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+  if (block === undefined) return [];
+  const lines = block.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+  if (start === -1) return [];
+  const inline = (lines[start] ?? "").slice(key.length + 1).trim();
+  if (inline) return parseList(inline);
+  const items: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    const item = line.match(/^\s*-\s+(.*)$/)?.[1];
+    if (item === undefined) break;
+    items.push(item.trim().replace(/^["']|["']$/g, ""));
+  }
+  return items;
+}
+
 export function stripLeadingHeading(body: string): string {
   const lines = body.split(/\r?\n/);
   let index = 0;
@@ -170,7 +194,8 @@ export function readTexts(textsRoot: string): Map<string, LocaleText & { id: str
   for (const file of readdirSync(textsRoot)
     .filter((name) => name.endsWith(".md"))
     .sort()) {
-    const { data, body } = parseFrontmatter(readFileSync(join(textsRoot, file), "utf8"));
+    const raw = readFileSync(join(textsRoot, file), "utf8");
+    const { data, body } = parseFrontmatter(raw);
     const id = data["screenId"] || basename(file, ".md");
     const bodyMd = stripLeadingHeading(body);
     texts.set(id, {
@@ -179,7 +204,10 @@ export function readTexts(textsRoot: string): Map<string, LocaleText & { id: str
       bodyMd,
       dir: textsRoot,
       gruppe: data["gruppe"] || undefined,
+      start: data["start"] || undefined,
       prozesse: parseList(data["prozesse"]),
+      questions: parseFrontmatterList(raw, "fragen"),
+      screens: parseFrontmatterList(raw, "masken"),
       uiIgnore: parseList(data["ui-ignore"]),
       staleTerms: [],
       missingImages: localImageRefs(bodyMd).filter(
@@ -190,6 +218,16 @@ export function readTexts(textsRoot: string): Map<string, LocaleText & { id: str
   return texts;
 }
 
+// Prefixed so a process page never shares an id with a screen chapter.
+function readProcessTexts(textsRoot: string): Map<string, LocaleText & { id: string }> {
+  const processTexts = new Map<string, LocaleText & { id: string }>();
+  for (const [rawId, text] of readTexts(textsRoot)) {
+    const id = `${PROCESS_ID_PREFIX}${rawId}`;
+    processTexts.set(id, { ...text, id, gruppe: PROCESS_GROUP_ID });
+  }
+  return processTexts;
+}
+
 export function discoverMatrix(
   shotsDir: string,
   locales: readonly string[],
@@ -395,19 +433,12 @@ function registerChapters(
   return { chapters, sourceOrder, configGroupOf };
 }
 
-export async function buildModel(
+function loadTextsByLocale(
   config: HandbuchConfig,
   options: BuildModelOptions,
-): Promise<Model> {
-  const repoDir = resolve(options.rootDir, config.repo);
-  const screens =
-    options.screens ??
-    config.screens ??
-    (config.screensModule
-      ? await loadScreensModule(options.rootDir, config.repo, config.screensModule)
-      : []);
-
-  const textsByLocale = new Map(
+  repoDir: string,
+): Map<string, Map<string, LocaleText>> {
+  return new Map(
     config.locales.map((locale) => [
       locale,
       readTexts(
@@ -417,19 +448,63 @@ export async function buildModel(
       ),
     ]),
   );
-  const applyStale = (
-    byLocale: Map<string, Map<string, LocaleText>>,
-    uiStrings: Map<string, string[]>,
-  ) => {
-    const uiIndex = buildUiIndex(uiStrings);
-    for (const [locale, texts] of byLocale) {
-      for (const text of texts.values()) {
-        text.staleTerms = findMissingUiTerms(text.bodyMd, locale, uiIndex, text.uiIgnore);
-      }
+}
+
+function applyStaleTerms(
+  byLocale: Map<string, Map<string, LocaleText>>,
+  uiStrings: Map<string, string[]>,
+): void {
+  const uiIndex = buildUiIndex(uiStrings);
+  for (const [locale, texts] of byLocale) {
+    for (const text of texts.values()) {
+      text.staleTerms = findMissingUiTerms(text.bodyMd, locale, uiIndex, text.uiIgnore);
     }
-  };
+  }
+}
+
+function mergeProcessTexts(
+  config: HandbuchConfig,
+  repoDir: string,
+  textsByLocale: Map<string, Map<string, LocaleText>>,
+): Set<string> {
+  const processIds = new Set<string>();
+  const processTextsDir = config.processTextsDir;
+  if (!processTextsDir) return processIds;
+  for (const locale of config.locales) {
+    const processTexts = readProcessTexts(
+      join(repoDir, processTextsDir.replace("{locale}", locale)),
+    );
+    for (const [id, text] of processTexts) {
+      textsByLocale.get(locale)?.set(id, text);
+      processIds.add(id);
+    }
+  }
+  return processIds;
+}
+
+function markProcessChapters(chapters: Map<string, Chapter>, processIds: Set<string>): void {
+  for (const id of processIds) {
+    const chapter = chapters.get(id);
+    if (chapter) chapter.isProcess = true;
+  }
+}
+
+export async function buildModel(
+  config: HandbuchConfig,
+  options: BuildModelOptions,
+): Promise<Model> {
+  const repoDir = resolve(options.rootDir, config.repo);
+  const screens =
+    options.screens ??
+    config.screens ??
+    (config.screensModule
+      ? await loadScreensModule(options.rootDir, config.repo, config.screensModule)
+      : []);
+
+  const textsByLocale = loadTextsByLocale(config, options, repoDir);
+  const processIds = mergeProcessTexts(config, repoDir, textsByLocale);
   if (config.uiStrings || config.uiStringPackages) {
-    applyStale(
+    applyStaleTerms(
       textsByLocale,
       collectUiStrings({
         repoDir,
@@ -445,6 +520,10 @@ export async function buildModel(
     ...group,
     label: tr?.groups[group.id] ?? group.label,
   });
+  const processGroups: Group[] =
+    processIds.size > 0 && !config.groups.some((group) => group.id === PROCESS_GROUP_ID)
+      ? [labelGroup({ id: PROCESS_GROUP_ID, label: chromeFor(config.defaultLocale).processGroup })]
+      : [];
   const fallbackGroupDefault: Group = {
     id: FALLBACK_GROUP_ID,
     label: chromeFor(config.defaultLocale).fallbackGroup,
@@ -454,7 +533,7 @@ export async function buildModel(
     config,
     options,
     textsByLocale,
-    applyStale,
+    applyStaleTerms,
     labelGroup,
   );
   const shotsDir =
@@ -463,13 +542,14 @@ export async function buildModel(
     ? discoverMatrix(shotsDir, config.locales)
     : new Map<string, Map<string, MatrixShots>>();
 
-  const groups: Group[] = [...config.groups.map(labelGroup), ...flowGroups];
+  const groups: Group[] = [...config.groups.map(labelGroup), ...flowGroups, ...processGroups];
   const { chapters, sourceOrder, configGroupOf } = registerChapters(
     screens,
     flowChapters,
     textsByLocale,
     matrix,
   );
+  markProcessChapters(chapters, processIds);
 
   const fallbackGroup = assignGroups(config, chapters, groups, configGroupOf, fallbackGroupDefault);
   return assembleModel(config, chapters, groups, sourceOrder, fallbackGroup);