bazis 0.126.0 → 0.128.0

package/cli/generateModule.ts

@@ -39,7 +39,7 @@ export interface GenerateModuleResult {
   readonly warnings: readonly string[];
 }
 
-interface PlannedWrite {
+export interface PlannedWrite {
   readonly absolute: string;
   readonly content: string;
   readonly original: string | undefined;
@@ -82,7 +82,7 @@ export async function generateModulePack(options: GenerateModulePackOptions): Pr
 }
 
 /** The existing composite module `name` under `modulesRoot`: `Catalog` → `catalog_modules/Catalog.module.ts`. */
-async function findPack(modulesRoot: string, name: string): Promise<{ readonly dir: string; readonly entry: string; readonly moduleClass: string }> {
+export async function findPack(modulesRoot: string, name: string): Promise<{ readonly dir: string; readonly entry: string; readonly moduleClass: string }> {
   const naming = parseModuleName(name);
   const dir = path.join(modulesRoot, `${naming.folder}_modules`);
   const entry = path.join(dir, `${naming.module}.module.ts`);
@@ -150,7 +150,7 @@ async function generateFiles(options: GenerateModuleOptions, naming: ModuleNamin
   };
 }
 
-async function fileInfo(absolute: string) {
+export async function fileInfo(absolute: string) {
   try {
     return await lstat(absolute);
   } catch (error) {
@@ -161,7 +161,7 @@ async function fileInfo(absolute: string) {
 }
 
 /** Relative imports must survive runtime realpath resolution (e.g. /var -> /private/var). */
-async function canonicalDirectory(directory: string): Promise<string> {
+export async function canonicalDirectory(directory: string): Promise<string> {
   try {
     return await realpath(directory);
   } catch (error) {
@@ -172,7 +172,7 @@ async function canonicalDirectory(directory: string): Promise<string> {
   }
 }
 
-async function commitWrites(writes: readonly PlannedWrite[]): Promise<void> {
+export async function commitWrites(writes: readonly PlannedWrite[]): Promise<void> {
   const completed: PlannedWrite[] = [];
   const createdDirectories = new Set<string>();
   try {

package/cli/generateProcess.ts

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { canonicalDirectory, commitWrites, fileInfo, findPack, type GenerateModuleResult, type PlannedWrite } from "./generateModule";
+import { registerInModuleField } from "./moduleRegistration";
+import { parseModuleName } from "./naming";
+import { packPartFolder } from "./templates/pack";
+import { buildProcessTemplate } from "./templates/process";
+
+export interface GenerateProcessOptions {
+  /** OrderApproval, order-approval. */
+  readonly name: string;
+  /** The module that owns the process: `Orders` → `{modulesRoot}/orders/Orders.module.ts`. */
+  readonly module: string;
+  /** The composite module the owner is a part of. */
+  readonly pack?: string;
+  /** Default: src/app/modules, relative to cwd. */
+  readonly modulesRoot?: string;
+  readonly force?: boolean;
+  readonly dryRun?: boolean;
+}
+
+/**
+ * Creates `processes/<Name>.process.ts` in a module and lists the process in
+ * the module's `@Module({ processes })` (WORKFLOW-001 §14).
+ */
+export async function generateProcess(options: GenerateProcessOptions): Promise<GenerateModuleResult> {
+  const naming = parseModuleName(options.name);
+  const owner = parseModuleName(options.module);
+  const modulesRoot = await canonicalDirectory(path.resolve(options.modulesRoot ?? "src/app/modules"));
+  const pack = options.pack === undefined ? undefined : await findPack(modulesRoot, options.pack);
+  const moduleDir = pack ? path.join(pack.dir, packPartFolder(owner)) : path.join(modulesRoot, owner.folder);
+  const moduleFile = path.join(moduleDir, `${owner.module}.module.ts`);
+  const moduleInfo = await fileInfo(moduleFile);
+  if (moduleInfo?.isFile() !== true) {
+    throw new Error(`Module ${owner.moduleClass} not found: ${path.relative(process.cwd(), moduleFile)}.${pack ? "" : " For a part of a composite module add --pack <Name>."}`);
+  }
+  const processFile = path.join(moduleDir, "processes", `${naming.module}.process.ts`);
+  const existing = await fileInfo(processFile);
+  if (existing && !options.force) throw new Error(`File already exists: ${processFile}. Use --force to overwrite.`);
+  if (existing && !existing.isFile()) throw new Error(`Refusing to overwrite a non-regular file: ${processFile}`);
+  const moduleSource = await readFile(moduleFile, "utf8");
+  const writes: PlannedWrite[] = [
+    { absolute: processFile, content: buildProcessTemplate(naming, owner.moduleClass), original: existing ? await readFile(processFile, "utf8") : undefined },
+    { absolute: moduleFile, content: registerInModuleField(moduleSource, moduleFile, processFile, `${naming.module}Process`, { field: "processes", hostClass: owner.moduleClass }), original: moduleSource },
+  ];
+  const changed = writes.filter((write) => write.content !== write.original);
+  if (!options.dryRun) await commitWrites(changed);
+  return {
+    moduleDir,
+    files: [path.relative(process.cwd(), processFile)],
+    registered: true,
+    dryRun: options.dryRun === true,
+    warnings: [],
+    changes: changed.map((write) => ({ path: path.relative(process.cwd(), write.absolute), action: write.original === undefined ? "create" : "update" })),
+  };
+}

package/cli/main.ts

@@ -6,12 +6,18 @@ import { parseCliArgs, type ParsedGenerateArgs } from "./parseCli";
 import { runCodegen, type CodegenOptions } from "./codegen";
 import { generateProject } from "./generateProject";
 import { runBuild, runDev, runTest } from "./build";
+import type { ParsedProcessArgs } from "./parseCli";
 import { bazisVersion, commandFailed, commandHeader, createScreens, lineOutput, requiredBun, type CliOutput } from "./ui";
 
 export const USAGE = `Usage:
   bazis new <Name> [options]                  Create a new application project
   bazis g module <Name> [options]             Atomic module (alias: m)
   bazis g pack <Name> --parts <a,b> [options] Composite module (aliases: p, module-pack)
+  bazis g process <Name> --module <Name>      Process in code: processes/<Name>.process.ts in the module,
+                                             listed in its @Module processes (alias: pr; --pack <Name>
+                                             for a part of a composite module)
+  bazis workflow check [--app-module <path>]  Check the processes of the modules against their Tools
+  bazis workflow diagram <key>                Print a process as a Mermaid flowchart
   bazis codegen [--target <name|all>]         Generate DI wiring into src/generated/bazis
   bazis dev [--watch]                         Codegen, then run the app from source with
                                              BAZIS_ENV=development (unless set);
@@ -58,6 +64,9 @@ Examples (from the project root):
   bunx bazis g module Mailer --empty --no-register
   bunx bazis g pack DataManager --parts tables,fields,validators,records
   bunx bazis g module Prices --empty --pack Catalog
+  bunx bazis g process OrderApproval --module Orders
+  bunx bazis workflow check
+  bunx bazis workflow diagram order-approval > order-approval.mmd
   bunx bazis codegen --target production
   bunx bazis dev --watch
   bunx bazis test
@@ -134,15 +143,40 @@ export async function runCli(argv: readonly string[], runtime: CliRuntime = defa
     if (parsed.kind === "test") return await runTest(cwd, parsed.args, codegen, ui);
     if (parsed.kind === "build") return await runBuild(cwd, { bin: parsed.bin, outfile: parsed.outfile, dotenv: parsed.dotenv, platform: parsed.platform }, codegen, ui);
     if (parsed.kind === "new") return await runNew(parsed, ui);
+    if (parsed.kind === "workflow") {
+      const { runWorkflowCheck, runWorkflowDiagram } = await import("./workflow");
+      return parsed.action === "check" ? await runWorkflowCheck(cwd, parsed.appModule, ui) : await runWorkflowDiagram(cwd, parsed.key, parsed.appModule, runtime.log);
+    }
     // Module registration parses the host module with the TypeScript API: load it
     // only after switching TypeScript 7 to @typescript/typescript6.
     useTypeScriptCompilerApi(cwd);
+    if (parsed.kind === "process") return await runGenerateProcess(cwd, parsed.args, ui);
     return await runGenerate(cwd, parsed.args, codegen, ui);
   } catch (error) {
-    return commandFailed(ui.err, ui.err.t.failure.command, [{ tag: "CLI", where: parsed.kind === "generate" ? `g ${parsed.args.generator}` : parsed.kind, cause: error instanceof Error ? error.message : String(error) }], 1);
+    return commandFailed(ui.err, ui.err.t.failure.command, [{ tag: "CLI", where: parsed.kind === "generate" ? `g ${parsed.args.generator}` : parsed.kind === "process" ? "g process" : parsed.kind === "workflow" ? `workflow ${parsed.action}` : parsed.kind, cause: error instanceof Error ? error.message : String(error) }], 1);
   }
 }
 
+async function runGenerateProcess(cwd: string, args: ParsedProcessArgs, ui: CliOutput): Promise<number> {
+  const s = ui.out;
+  const t = s.t;
+  const { generateProcess } = await import("./generateProcess");
+  commandHeader(s, "gen", cwd, [
+    s.kv(t.workflow.processKind, s.strong(args.name)),
+    s.kv(t.noun("module", 1), s.text(args.pack === undefined ? args.module : `${args.pack} / ${args.module}`)),
+    ...(args.dryRun ? [s.fg(PALETTE.yellow, t.common.dryRun)] : []),
+  ]);
+  const result = await generateProcess(args);
+  s.section(t.section.files, s.muted(path.relative(cwd, result.moduleDir) || result.moduleDir));
+  s.step("ok", t.step.files, s.num(result.changes.length, t.noun("change", result.changes.length)));
+  s.tree(result.changes.map((change) => ({ text: `${change.action === "create" ? s.strong("+", PALETTE.lime) : s.strong("~", PALETTE.yellow)} ${s.text(change.path)}` })), s.style.color ? 9 : 4);
+  const host = result.changes.find((change) => change.action === "update")?.path;
+  if (host !== undefined) s.line(`  ${s.strong("↗", PALETTE.export)}  ${s.text(t.workflow.processRegistered(host))}`);
+  s.line();
+  s.banner("success", result.dryRun ? t.workflow.processPlanned(args.name) : t.workflow.processCreated(args.name));
+  return 0;
+}
+
 async function runCodegenCommand(cwd: string, target: string | undefined, codegen: CliRuntime["codegen"], ui: CliOutput): Promise<number> {
   const s = ui.out;
   const t = s.t;

package/cli/moduleRegistration.ts

@@ -10,9 +10,19 @@ export function moduleImportPath(fromFile: string, moduleFile: string): string {
 
 /** Edits only the import and the selected @Module metadata, preserving other source text. */
 export function registerModuleInSource(content: string, appFile: string, moduleFile: string, moduleClass: string): string {
+  return registerInModuleField(content, appFile, moduleFile, moduleClass, { field: "imports", hostClass: "AppModule" });
+}
+
+/**
+ * Adds `moduleClass` (an export of `moduleFile`) to the array `field` of the
+ * `@Module` in `appFile` and imports it: `imports` for a module, `processes`
+ * for a process. The class named `hostClass` is chosen, or the only one.
+ */
+export function registerInModuleField(content: string, appFile: string, moduleFile: string, moduleClass: string, options: { readonly field: string; readonly hostClass?: string }): string {
+  const { field } = options;
   const diagnostics = ts.transpileModule(content, { fileName: appFile, reportDiagnostics: true }).diagnostics ?? [];
   if (diagnostics.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
-    throw new Error(`Cannot register a module in invalid TypeScript: ${appFile}`);
+    throw new Error(`Cannot register in invalid TypeScript: ${appFile}`);
   }
   const source = ts.createSourceFile(appFile, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
   const importPath = moduleImportPath(appFile, moduleFile);
@@ -75,26 +85,26 @@ export function registerModuleInSource(content: string, appFile: string, moduleF
       candidates.push({ name: statement.name?.text, metadata });
     }
   }
-  const candidate = candidates.find((item) => item.name === "AppModule") ?? (candidates.length === 1 ? candidates[0] : undefined);
-  if (!candidate) throw new Error("Could not select a unique @Module class for registration in App.module.ts.");
+  const candidate = candidates.find((item) => item.name === options.hostClass) ?? (candidates.length === 1 ? candidates[0] : undefined);
+  if (!candidate) throw new Error(`Could not select a unique @Module class for registration in ${path.basename(appFile)}.`);
   const metadata = candidate.metadata;
   if (metadata.properties.some(ts.isSpreadAssignment)) throw new Error("Automatic registration does not support spread @Module metadata; register the module explicitly.");
   if (metadata.properties.some((property) => property.name && ts.isComputedPropertyName(property.name))) throw new Error("Automatic registration does not support computed @Module properties; register the module explicitly.");
-  const importProperties = metadata.properties.filter((property) => property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text === "imports");
-  if (importProperties.length > 1) throw new Error("Duplicate imports properties in @Module metadata.");
+  const importProperties = metadata.properties.filter((property) => property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text === field);
+  if (importProperties.length > 1) throw new Error(`Duplicate ${field} properties in @Module metadata.`);
   const property = importProperties[0];
   const edits: Edit[] = [];
   if (property) {
     if (!ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
-      throw new Error("@Module imports must be an array literal for automatic registration.");
+      throw new Error(`@Module ${field} must be an array literal for automatic registration.`);
     }
     const array = property.initializer;
-    if (array.elements.some(ts.isOmittedExpression)) throw new Error("@Module imports contains an empty element; fix the array before registration.");
+    if (array.elements.some(ts.isOmittedExpression)) throw new Error(`@Module ${field} contains an empty element; fix the array before registration.`);
     if (!array.elements.some((element) => ts.isIdentifier(element) && element.text === binding)) {
       appendMember(content, array, array.elements, binding, edits, eol);
     }
   } else {
-    appendMember(content, metadata, metadata.properties, `imports: [${binding}]`, edits, eol);
+    appendMember(content, metadata, metadata.properties, `${field}: [${binding}]`, edits, eol);
   }
   if (!imported) {
     const lastImport = imports.at(-1);
@@ -110,12 +120,15 @@ export function registerModuleInSource(content: string, appFile: string, moduleF
 function appendMember(content: string, node: ts.Node, members: ts.NodeArray<ts.Node>, member: string, edits: Edit[], eol: string): void {
   const close = node.end - 1;
   const last = members.at(-1);
-  if (last && !members.hasTrailingComma) edits.push({ at: last.end, text: "," });
   const inner = content.slice(node.getStart() + 1, close);
   if (!inner.includes("\n")) {
-    edits.push({ at: close, text: `${last || inner.trim() ? " " : ""}${member}${members.hasTrailingComma ? "," : ""}` });
+    // One line: right after the last member (and its comma), `{ a, b }` → `{ a, b, c }`.
+    if (!last) edits.push({ at: close, text: inner.length > 0 ? `${member} ` : member });
+    else if (members.hasTrailingComma) edits.push({ at: content.indexOf(",", last.end) + 1, text: ` ${member},` });
+    else edits.push({ at: last.end, text: `, ${member}` });
     return;
   }
+  if (last && !members.hasTrailingComma) edits.push({ at: last.end, text: "," });
   const lineStart = content.lastIndexOf("\n", close) + 1;
   const closingIndent = content.slice(lineStart, close);
   if (/^\s*$/.test(closingIndent)) {

package/cli/parseCli.ts

@@ -18,11 +18,24 @@ export interface ParsedGenerateArgs {
   readonly target?: string;
 }
 
+export interface ParsedProcessArgs {
+  readonly name: string;
+  /** The module that owns the process. */
+  readonly module: string;
+  readonly pack?: string;
+  readonly modulesRoot?: string;
+  readonly force: boolean;
+  readonly dryRun: boolean;
+}
+
 export type ParseCliResult =
   | { readonly kind: "help"; readonly help: boolean }
   | { readonly kind: "version" }
   | { readonly kind: "new"; readonly name: string; readonly outputPath?: string; readonly frameworkPath?: string; readonly linkFramework: boolean; readonly vendor: boolean; readonly dryRun: boolean }
   | { readonly kind: "generate"; readonly args: ParsedGenerateArgs }
+  | { readonly kind: "process"; readonly args: ParsedProcessArgs }
+  | { readonly kind: "workflow"; readonly action: "check"; readonly appModule?: string }
+  | { readonly kind: "workflow"; readonly action: "diagram"; readonly key: string; readonly appModule?: string }
   | { readonly kind: "codegen"; readonly target?: string }
   | { readonly kind: "dev"; readonly watch: boolean }
   | { readonly kind: "test"; readonly args: readonly string[] }
@@ -33,7 +46,7 @@ const GENERATOR_ALIASES = new Map<string, "module" | "pack">([
   ["module", "module"], ["m", "module"],
   ["pack", "pack"], ["p", "pack"], ["module-pack", "pack"],
 ]);
-const VALUE_OPTIONS = new Set(["--modules-root", "--app-module", "--pack", "--parts", "--target", "--path", "--framework", "--outfile", "--platform"]);
+const VALUE_OPTIONS = new Set(["--modules-root", "--app-module", "--pack", "--module", "--parts", "--target", "--path", "--framework", "--outfile", "--platform"]);
 /** Platforms of `bun build --compile --target=bun-<platform>`. */
 export const BINARY_PLATFORM = /^(linux|darwin|windows)-(x64|arm64)(-musl)?(-baseline|-modern)?$/;
 const FLAG_OPTIONS = new Set(["--no-register", "--force", "--full", "--enterprise", "--minimal", "--empty", "--dry-run", "--no-codegen", "--link-framework", "--vendor", "--bin", "--watch", "--dotenv"]);
@@ -114,13 +127,42 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
     }
     return { kind: "codegen", target };
   }
+  if (command === "workflow") {
+    for (const option of options.keys()) {
+      if (option !== "--app-module") return error(`Option ${option} is not supported by workflow.`);
+    }
+    const appModule = options.get("--app-module");
+    if (generatorToken === "check" && positional.length === 2) return { kind: "workflow", action: "check", ...(appModule === undefined ? {} : { appModule }) };
+    if (generatorToken === "diagram" && positional.length === 3) return { kind: "workflow", action: "diagram", key: name!, ...(appModule === undefined ? {} : { appModule }) };
+    return error("Use: bazis workflow check [--app-module <path>] or bazis workflow diagram <key> [--app-module <path>]");
+  }
+  if (options.has("--module") && !((command === "g" || command === "generate") && (generatorToken === "process" || generatorToken === "pr"))) return error("--module is only supported by g process.");
+  if ((command === "g" || command === "generate") && (generatorToken === "process" || generatorToken === "pr")) {
+    for (const option of options.keys()) {
+      if (!["--module", "--pack", "--modules-root", "--force", "--dry-run"].includes(option)) return error(`Option ${option} is not supported by g process.`);
+    }
+    if (name === undefined || positional.length !== 3) return error("Use: bazis g process <Name> --module <Name> [--pack <Name>]");
+    const module = options.get("--module");
+    if (module === undefined) return error("g process needs the module that owns the process: --module <Name>.");
+    try {
+      parseModuleName(name);
+      parseModuleName(module);
+      if (options.has("--pack")) parseModuleName(options.get("--pack")!);
+    } catch (cause) {
+      return error(cause instanceof Error ? cause.message : String(cause));
+    }
+    return {
+      kind: "process",
+      args: { name, module, pack: options.get("--pack"), modulesRoot: options.get("--modules-root"), force: options.has("--force"), dryRun: options.has("--dry-run") },
+    };
+  }
   if (command !== "g" && command !== "generate") {
     return error(`Unknown command: ${command ?? "(missing)"}. Use: bazis --help`);
   }
-  if (generatorToken === undefined) return error("Generator is required: module (m) or pack (p).");
+  if (generatorToken === undefined) return error("Generator is required: module (m), pack (p) or process (pr).");
   if (options.has("--path") || options.has("--framework") || options.has("--link-framework") || options.has("--vendor")) return error("--path, --framework, --link-framework and --vendor are only supported by new.");
   const generator = GENERATOR_ALIASES.get(generatorToken);
-  if (generator === undefined) return error(`Unknown generator: ${generatorToken}. Supported: module (m), pack (p)`);
+  if (generator === undefined) return error(`Unknown generator: ${generatorToken}. Supported: module (m), pack (p), process (pr)`);
   if (name === undefined) return error("Module name is required.");
   if (positional.length !== 3) return error(`Unexpected argument: ${positional[3]}`);
 

package/cli/templates/process.ts

@@ -0,0 +1,28 @@
+import type { ModuleNaming } from "../naming";
+
+/** `processes/<Name>.process.ts`: a manual start and an end, to grow into the real process. */
+export function buildProcessTemplate(process: ModuleNaming, moduleClass: string): string {
+  const title = process.folder.split("-").map((word, index) => (index === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word)).join(" ");
+  return `import { defineProcess } from "bazis/core/workflow";
+
+/**
+ * ${title}: a process of ${moduleClass}. It is published when the application
+ * starts and changes only here. Check it with \`bunx bazis workflow check\`,
+ * draw it with \`bunx bazis workflow diagram ${process.folder}\`.
+ */
+export const ${process.module}Process = defineProcess({
+  key: "${process.folder}",
+  title: "${title}",
+  document: {
+    schemaVersion: "bazis.workflow/v1",
+    nodes: {
+      Start: { kind: "manualStart", title: "Start" },
+      End: { kind: "end", title: "End" },
+    },
+    flows: {
+      f1: { source: "Start", target: "End" },
+    },
+  },
+});
+`;
+}

package/cli/workflow.ts

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { PALETTE } from "../library/terminal";
+import { processToMermaid } from "../library/workflow";
+import { isBazisModuleClass } from "../core/di/module/Module";
+import type { BazisModuleRef } from "../core/di";
+import { inspectProcesses, type ProcessInspection } from "../core/workflow/definitions_module/code/inspectProcesses";
+import { commandFailed, commandHeader, type CliOutput } from "./ui";
+
+/**
+ * The application's root module, imported without starting anything: the
+ * export `AppModule` of the app module file, or its only `@Module` class.
+ */
+export async function loadAppModule(cwd: string, appModule = "src/app/modules/App.module.ts"): Promise<{ readonly file: string; readonly root: BazisModuleRef }> {
+  const file = path.resolve(cwd, appModule);
+  if (!(await Bun.file(file).exists())) throw new Error(`App module not found: ${path.relative(cwd, file)}. Pass --app-module <path>.`);
+  const exports = await import(pathToFileURL(file).href) as Record<string, unknown>;
+  const modules = Object.entries(exports).filter(([, value]) => isBazisModuleClass(value));
+  const chosen = modules.find(([name]) => name === "AppModule") ?? (modules.length === 1 ? modules[0] : undefined);
+  if (!chosen) throw new Error(`${path.relative(cwd, file)} exports ${modules.length === 0 ? "no @Module class" : "several @Module classes and none is AppModule"}.`);
+  return { file, root: chosen[1] as BazisModuleRef };
+}
+
+/** `bazis workflow check`: every process of the module tree against the Tools; exit code 1 on errors. */
+export async function runWorkflowCheck(cwd: string, appModule: string | undefined, ui: CliOutput): Promise<number> {
+  const s = ui.out;
+  const t = s.t.workflow;
+  const { file, root } = await loadAppModule(cwd, appModule);
+  commandHeader(s, "workflow", cwd, [s.kv(t.app, s.text(path.relative(cwd, file)))]);
+  const inspection = inspectProcesses(root);
+  s.section(t.section, s.muted(`${inspection.processes.length} ${s.t.noun("process", inspection.processes.length)} · ${inspection.tools.length} ${s.t.noun("tool", inspection.tools.length)}`));
+  if (inspection.processes.length === 0) s.line(`  ${s.muted(t.none)}`);
+  for (const { process, module, errors, warnings } of inspection.processes) {
+    const nodes = Object.keys(process.document.nodes ?? {}).length;
+    s.step(errors.length > 0 ? "fail" : warnings.length > 0 ? "warn" : "ok", process.key, s.muted(`${module} · ${nodes} ${s.t.noun("node", nodes)}`));
+    s.tree([...errors.map((text) => ({ text: s.fg(PALETTE.red, text) })), ...warnings.map((text) => ({ text: s.fg(PALETTE.yellow, text) }))], s.style.color ? 9 : 4);
+  }
+  const errors = errorCount(inspection);
+  s.line();
+  if (errors > 0) {
+    const problems = [
+      ...inspection.errors.map((cause) => ({ tag: "WORKFLOW", where: "processes", cause })),
+      ...inspection.processes.filter((entry) => entry.errors.length > 0).map((entry) => ({ tag: "WORKFLOW", where: `${entry.module} · ${entry.process.key}`, cause: entry.errors.join("\n") })),
+    ];
+    return commandFailed(ui.err, t.failed(errors), problems, 1, t.fix);
+  }
+  s.banner("success", t.passed(inspection.processes.length));
+  return 0;
+}
+
+/** `bazis workflow diagram <key>`: the process as Mermaid on stdout, nothing else, so it can be redirected. */
+export async function runWorkflowDiagram(cwd: string, key: string, appModule: string | undefined, log: (text: string) => void): Promise<number> {
+  const { root } = await loadAppModule(cwd, appModule);
+  const inspection = inspectProcesses(root);
+  const entry = inspection.processes.find(({ process }) => process.key === key);
+  if (!entry) {
+    const keys = inspection.processes.map(({ process }) => process.key);
+    throw new Error(`No process "${key}" is declared in code. ${keys.length === 0 ? "The modules declare no processes." : `Declared: ${keys.join(", ")}.`}`);
+  }
+  log(processToMermaid(entry.process.document).trimEnd());
+  return 0;
+}
+
+function errorCount(inspection: ProcessInspection): number {
+  return inspection.errors.length + inspection.processes.reduce((sum, entry) => sum + entry.errors.length, 0);
+}

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.126.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.128.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/workflow/Workflow.module.ts

@@ -3,13 +3,15 @@ import { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefiniti
 import { IWorkflowDefinitions } from "./definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
 import { IWorkflowRuntime } from "./runtime_module/services/IWorkflowRuntime.service";
+import { WorkflowTasksModule } from "./tasks_module/WorkflowTasks.module";
+import { IWorkflowTasks } from "./tasks_module/services/IWorkflowTasks.service";
 
 /**
  * Business processes (WORKFLOW-001): the pack only assembles its parts
  * ([passport](MODULE.md)). An application imports it, or only the parts it needs.
  */
 @Module({
-  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule],
-  exports: [IWorkflowDefinitions, IWorkflowRuntime],
+  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule, WorkflowTasksModule],
+  exports: [IWorkflowDefinitions, IWorkflowRuntime, IWorkflowTasks],
 })
 export class WorkflowModule {}

package/core/workflow/contracts/WorkflowClock.ts

@@ -0,0 +1,21 @@
+/**
+ * Where the engine takes the time from (WORKFLOW-001 §14): due times of timers,
+ * retries, scheduled starts and job delays, the retention cutoff and task marks.
+ * Record stamps (`createdAt`, history `at`) stay the database's time. The
+ * default is the system clock; tests replace it (`bazis/core/workflow/testing`).
+ */
+export abstract class WorkflowClock {
+  abstract now(): Date;
+  /**
+   * Time moves only when a test moves it: the worker and retention then leave
+   * the jobs to the test's `drain`, so nothing runs behind its back.
+   */
+  readonly manual?: boolean;
+}
+
+/** The system clock. */
+export class SystemWorkflowClock extends WorkflowClock {
+  now(): Date {
+    return new Date();
+  }
+}

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -1,5 +1,9 @@
-import { DI, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
 import { WorkflowTools } from "../internal/WorkflowTools";
+import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
+import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
+import { codeProcessesOf } from "./code/codeProcesses";
 import { ProcessesController } from "./http/Processes.controller";
 import { DefinitionsDbContext, definitionsStore } from "./model/Definitions.dbContext";
 import { WfProcess } from "./model/WfProcess.model";
@@ -8,17 +12,21 @@ import { IWorkflowDefinitions } from "./services/IWorkflowDefinitions.service";
 import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
 
 /**
- * The process catalog: drafts and published versions ([passport](MODULE.md)).
- * Dependencies are explicit: the framework's classes are not covered by the
- * application's codegen.
+ * The process catalog: drafts and published versions, and the processes
+ * declared in code ([passport](MODULE.md)). Dependencies are explicit: the
+ * framework's classes are not covered by the application's codegen.
  */
 @Module({
   ormBazis: { context: DefinitionsDbContext, entities: [WfProcess, WfVersion], ownedStore: definitionsStore, registerRepositories: false },
   providers: [
+    DI.singleton(DI.factoryProvider(WorkflowClock, [], () => new SystemWorkflowClock())),
     DI.singleton(DI.factoryProviderWithResolver(WorkflowTools, [], (resolver) => new WorkflowTools(resolver.resolve(SERVICE_PROVIDER)))),
-    scoped(IWorkflowDefinitions, WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools] as const),
+    DI.singleton(DI.factoryProviderWithResolver(CodeProcessCatalog, [], (resolver) => new CodeProcessCatalog(codeProcessesOf(resolver.resolve(SERVICE_PROVIDER))))),
+    scoped(WorkflowDefinitions, WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock] as const),
+    DI.scoped(DI.factoryProviderWithResolver(IWorkflowDefinitions, [], (resolver) => resolver.resolve(WorkflowDefinitions))),
+    DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => new CodeProcessPublisher(resolver.resolve(SERVICE_PROVIDER)))),
   ],
   controllers: [DI.bindDeps(ProcessesController, IWorkflowDefinitions)],
-  exports: [IWorkflowDefinitions, WorkflowTools],
+  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/code/CodeProcessCatalog.ts

@@ -0,0 +1,19 @@
+import type { OwnedCodeProcess } from "./codeProcesses";
+
+/** The processes declared in the application's modules, by key: which module owns a key. */
+export class CodeProcessCatalog {
+  private readonly byKey: ReadonlyMap<string, OwnedCodeProcess>;
+
+  constructor(entries: readonly OwnedCodeProcess[]) {
+    this.byKey = new Map([...entries].sort((a, b) => a.process.key.localeCompare(b.process.key)).map((entry) => [entry.process.key, entry]));
+  }
+
+  /** The module whose `processes` declare `key`; `undefined` for a process of the catalog. */
+  moduleOf(key: string): string | undefined {
+    return this.byKey.get(key)?.module;
+  }
+
+  list(): readonly OwnedCodeProcess[] {
+    return [...this.byKey.values()];
+  }
+}

package/core/workflow/definitions_module/code/CodeProcessPublisher.ts

@@ -0,0 +1,44 @@
+import { markConfigurationError, type ServiceProvider } from "../../../di";
+import type { HostedService } from "../../../di/extensions/hosted-service";
+import { LOGGER } from "../../../kernel";
+import { WorkflowTools } from "../../internal/WorkflowTools";
+import { WorkflowDefinitions } from "../services/WorkflowDefinitions.service";
+import { CodeProcessCatalog } from "./CodeProcessCatalog";
+import { definitionProblems, WorkflowSetupError } from "./codeProcesses";
+
+/**
+ * Publishes the processes of `@Module({ processes })` at start, after the
+ * tables exist (WORKFLOW-001 §14). A document with an unknown Tool stops the
+ * start with every finding of every process; the same document again gives no
+ * new version.
+ */
+export class CodeProcessPublisher implements HostedService {
+  readonly diagnosticName = "workflow:processes";
+
+  constructor(private readonly services: ServiceProvider) {}
+
+  async start(): Promise<void> {
+    const entries = this.services.resolve(CodeProcessCatalog).list();
+    if (entries.length === 0) return;
+    const tools = this.services.resolve(WorkflowTools);
+    const problems = entries.flatMap(({ process, module }) => {
+      const found = definitionProblems(process, (name) => tools.has(name));
+      return found.length === 0 ? [] : [`${module}: process "${process.key}":\n${found.map((line) => `  - ${line}`).join("\n")}`];
+    });
+    if (problems.length > 0) {
+      throw markConfigurationError(new WorkflowSetupError(`Processes declared in code cannot be published:\n${problems.join("\n")}`));
+    }
+    const scope = this.services.createScope();
+    try {
+      const results = await scope.resolve(WorkflowDefinitions).publishCode(entries);
+      this.services.tryResolve(LOGGER)?.info("workflow processes from code", {
+        published: results.filter((result) => result.published).map((result) => `${result.key} v${result.version}`),
+        unchanged: results.filter((result) => !result.published).map((result) => result.key),
+      });
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  stop(): void {}
+}