bazis 0.127.0 → 0.128.0

package/library/terminal/messages.ts

@@ -32,6 +32,8 @@ const NOUNS_EN = {
   change: ["change", "changes", "changes"],
   part: ["part", "parts", "parts"],
   context: ["database context", "database contexts", "database contexts"],
+  process: ["process", "processes", "processes"],
+  node: ["node", "nodes", "nodes"],
 } as const satisfies Record<string, Forms>;
 
 export type Noun = keyof typeof NOUNS_EN;
@@ -60,6 +62,8 @@ const NOUNS_RU: Record<Noun, Forms> = {
   change: ["изменение", "изменения", "изменений"],
   part: ["часть", "части", "частей"],
   context: ["контекст базы данных", "контекста базы данных", "контекстов базы данных"],
+  process: ["процесс", "процесса", "процессов"],
+  node: ["узел", "узла", "узлов"],
 };
 
 /** Genitive after «из N»: «из 1 подключения», «из 3 подключений», «из 21 подключения». */
@@ -239,6 +243,18 @@ const en = {
     needsCache: "this module caches: pass runApp(AppModule, { cache: memory() })",
     keptOnFailure: "scaffold files were kept — fix the error and run bazis codegen",
   },
+  workflow: {
+    app: "app",
+    section: "PROCESSES IN CODE",
+    none: "no module declares processes — add one with bazis g process <Name> --module <Name>",
+    passed: (count: number) => `${count} ${formEn(count, NOUNS_EN.process)} checked`,
+    failed: (count: number) => `process check failed · ${count} ${formEn(count, NOUNS_EN.error)}`,
+    fix: "fix the documents or the Tools: the application refuses to start with these errors",
+    processKind: "process",
+    processCreated: (name: string) => `process ${name} is generated`,
+    processPlanned: (name: string) => `process ${name} is planned`,
+    processRegistered: (host: string) => `listed in processes of ${host}`,
+  },
   errors: {
     unknown: "Use bazis --help to list commands and options.",
     bunTooOld: (required: string, actual: string) => `bazis needs Bun ${required.startsWith(">=") ? `${required.slice(2).trim()} or newer` : required}; this is Bun ${actual}.`,
@@ -404,6 +420,18 @@ const ru: Messages = {
     needsCache: "модуль кэширует: передайте runApp(AppModule, { cache: memory() })",
     keptOnFailure: "файлы модуля оставлены — исправьте ошибку и запустите bazis codegen",
   },
+  workflow: {
+    app: "приложение",
+    section: "ПРОЦЕССЫ В КОДЕ",
+    none: "ни один модуль не объявляет процессы — добавьте процесс: bazis g process <Name> --module <Name>",
+    passed: (count) => `процессы в порядке · ${count} ${formRu(count, NOUNS_RU.process)}`,
+    failed: (count) => `проверка процессов не прошла · ${count} ${formRu(count, NOUNS_RU.error)}`,
+    fix: "исправьте документы или Tools: с этими ошибками приложение не запустится",
+    processKind: "процесс",
+    processCreated: (name) => `процесс ${name} создан`,
+    processPlanned: (name) => `процесс ${name} запланирован`,
+    processRegistered: (host) => `добавлен в processes модуля ${host}`,
+  },
   errors: {
     unknown: "Список команд и опций: bazis --help.",
     bunTooOld: (required, actual) => `bazis нужен Bun ${required.startsWith(">=") ? `${required.slice(2).trim()} или новее` : required}, а запущен Bun ${actual}.`,

package/library/terminal/screen.ts

@@ -58,6 +58,7 @@ export const MODE = Object.freeze({
   new: ["#ff2ee6", "#7b61ff"] as readonly string[],
   gen: ["#c77dff", "#ff2ee6"] as readonly string[],
   codegen: ["#00f0ff", "#c77dff"] as readonly string[],
+  workflow: ["#3dff7a", "#ffd60a"] as readonly string[],
 });
 
 /**

package/library/workflow/index.ts

@@ -22,4 +22,5 @@ export { DATA_PATH, isPath, readPath, resolveInput, type InstanceData } from "./
 export { evaluateCondition } from "./conditions";
 export { durationMs } from "./duration";
 export { parseCron, type CronSchedule } from "./cron";
+export { processToMermaid } from "./mermaid";
 export { checkFormSpec, formFieldCodes, validateForm, type FormField, type FormFieldType, type FormIssue, type FormSpec } from "./formFields";

package/library/workflow/mermaid.ts

@@ -0,0 +1,87 @@
+import type { Condition, NodeKind, ProcessDocument } from "./ProcessDocument";
+
+/** Words Mermaid reads as syntax: such node ids are renamed. */
+const RESERVED = new Set(["end", "graph", "flowchart", "subgraph", "style", "class", "classdef", "click", "default", "linkstyle", "direction"]);
+
+const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
+  manualStart: ["([", "])"],
+  scheduleStart: ["([", "])"],
+  eventStart: ["([", "])"],
+  end: ["((", "))"],
+  userTask: ["[", "]"],
+  serviceTask: ["[[", "]]"],
+  timerCatch: ["{{", "}}"],
+  eventWait: ["{{", "}}"],
+  exclusiveGateway: ["{", "}"],
+  parallelGateway: ["{", "}"],
+  boundaryError: ["((", "))"],
+  boundaryTimer: ["((", "))"],
+  boundaryEvent: ["((", "))"],
+};
+
+/**
+ * A process as a Mermaid `flowchart` (WORKFLOW-001 §14): starts are stadiums,
+ * Tool steps subroutines, tasks rectangles, waits hexagons, gateways rhombi,
+ * ends and boundary events circles. A boundary event hangs on its step by a
+ * dotted link. Labels show the node kind's detail: the Tool, the cron, the
+ * duration, the event key; flows show their title or condition.
+ */
+export function processToMermaid(document: ProcessDocument, direction: "LR" | "TB" = "LR"): string {
+  const ids = new Map<string, string>();
+  const used = new Set<string>();
+  const idOf = (nodeId: string): string => {
+    const known = ids.get(nodeId);
+    if (known !== undefined) return known;
+    let id = /^[A-Za-z][A-Za-z0-9_]*$/.test(nodeId) && !RESERVED.has(nodeId.toLowerCase()) ? nodeId : `n_${nodeId.replace(/[^A-Za-z0-9_]/g, "_")}`;
+    while (used.has(id)) id = `${id}_`;
+    used.add(id);
+    ids.set(nodeId, id);
+    return id;
+  };
+  const lines = [`flowchart ${direction}`];
+  for (const [nodeId, node] of Object.entries(document.nodes)) {
+    const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
+    const detail = detailOf(node.kind, node.config ?? {});
+    lines.push(`  ${idOf(nodeId)}${open}"${label(node.title || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}"${close}`);
+  }
+  for (const [nodeId, node] of Object.entries(document.nodes)) {
+    if (node.attachedTo !== undefined && document.nodes[node.attachedTo] !== undefined) lines.push(`  ${idOf(node.attachedTo)} -.- ${idOf(nodeId)}`);
+  }
+  for (const flow of Object.values(document.flows)) {
+    if (document.nodes[flow.source] === undefined || document.nodes[flow.target] === undefined) continue;
+    const text = flow.title ?? (flow.condition !== undefined ? conditionText(flow.condition) : flow.isDefault === true ? "default" : undefined);
+    lines.push(`  ${idOf(flow.source)} -->${text === undefined ? "" : `|"${label(text)}"|`} ${idOf(flow.target)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function detailOf(kind: NodeKind, config: Readonly<Record<string, unknown>>): string | undefined {
+  const text = (value: unknown) => (typeof value === "string" && value !== "" ? value : undefined);
+  switch (kind) {
+    case "serviceTask": return text(config.tool);
+    case "scheduleStart": return text(config.cron);
+    case "eventStart":
+    case "eventWait":
+    case "boundaryEvent": return text(config.event);
+    case "timerCatch":
+    case "boundaryTimer": return text(config.duration) ?? (text(config.at) === undefined ? undefined : `at ${config.at}`);
+    case "boundaryError": return text(config.errorCode);
+    case "userTask": {
+      const assignee = config.assignee as { role?: unknown; user?: unknown } | undefined;
+      return assignee === undefined ? undefined : text(assignee.role) !== undefined ? `role ${assignee.role}` : text(assignee.user) === undefined ? undefined : `user ${assignee.user}`;
+    }
+    default: return undefined;
+  }
+}
+
+function conditionText(condition: Condition): string {
+  if ("all" in condition) return condition.all.map(conditionText).join(" and ");
+  if ("any" in condition) return condition.any.map(conditionText).join(" or ");
+  if ("not" in condition) return `not (${conditionText(condition.not)})`;
+  return condition.op === "empty" || condition.op === "notEmpty" ? `${condition.path} ${condition.op}` : `${condition.path} ${condition.op} ${JSON.stringify(condition.value)}`;
+}
+
+/** Text inside a quoted Mermaid label: quotes and markup are entities. */
+function label(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "#quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.127.0",
+  "version": "0.128.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",
@@ -44,6 +44,7 @@
     "./core/testing": "./core/testing/index.ts",
     "./core/websocket": "./core/websocket/index.ts",
     "./core/workflow": "./core/workflow/index.ts",
+    "./core/workflow/testing": "./core/workflow/testing/index.ts",
     "./library/boundary": "./library/boundary/index.ts",
     "./library/http-client": "./library/http-client/index.ts",
     "./library/jsonapi": "./library/jsonapi/index.ts",