@sincpro/client-framework 0.4.0 → 0.5.0

package/README.md

@@ -179,6 +179,23 @@ await project.Issues.close(input); // span project/Issues.close
 await project.CloseAndNotify.execute(input); // project/CloseAndNotify → its Features under it
 ```
 
+The generator writes this skeleton for you, once, from the service's contract — and never touches
+a file that is already there, because from then on it is yours:
+
+```bash
+sincpro-client generate project.contract.json --out src/domains/project/generated --domain project
+sincpro-client scaffold project.contract.json --out src/domains/project   # dependencies, bases, services, index
+```
+
+And the layers stay layers: `sincpro-client check` resolves every import of the application with
+its own TypeScript and `tsconfig` (aliases included) and fails when a bounded context reaches into
+another's insides, a service imports React or web-ui, `common` imports a bounded context, or the
+entrypoints skip a bounded context's `index.ts` — put it in `make doctor`:
+
+```bash
+sincpro-client check --root src
+```
+
 Every public method is a use case: a span named as the backend names its own
 (`project/Issues.close`, identity `project.Issues.close`), and a report when it fails in a way
 nobody expected. One gesture is one trace, from the click to the database:
@@ -224,6 +241,10 @@ processContext.set({ tenant_id: "acme" }); // every use case runs with it and se
 project.context.set({ warehouse_id: 4 }); // only what «project» runs
 ```
 
+What a screen reads and writes is a use case too when it goes through `screensTransport(transport)`:
+each request is `screens/EntityReads.list`, `…/EntityWrites.send` — traced, with the context on
+it, and reported when it failed.
+
 A service reads it as `this.context` — the process's values, under them its bounded context's,
 under them a scope's, read once where the gesture started — and every request it sends carries
 it in `sincpro-context`. A screen hears it change with `processContext.watch(…)`.
@@ -263,6 +284,10 @@ const tracer = openTelemetryTracer(provider.getTracer("my-app")); // the app's p
 const reporter = sentryReporter(client); // the app's Sentry-compatible client (GlitchTip too)
 ```
 
+What fails outside a use case — a screen that broke while drawing, a subscriber, a worker — goes to
+the same reporter with `reportError(error, where)`: once (an error a use case already reported is
+not sent again), with the process's context.
+
 Nothing is installed or shipped unless it is imported, and without a tracer or a reporter every use
 case runs the same — nothing traces, nothing reports. In a test, `memoryTracer()` and
 `memoryReporter()` (`@sincpro/client-framework/testing`).
@@ -344,6 +369,9 @@ three ports, in its `main`:
 | `ContextStore`  | memory, `sessionStorage`, or the screens' store | MMKV, or memory hydrated from AsyncStorage | `memoryContexts`  |
 | `Transport`     | `restTransport` over `fetch`                    | `restTransport`, or SQLite offline         | `memoryTransport` |
 
+How @sincpro/mobile adopts all of this — what maps to what, the MMKV store, the order to move
+in — is [`docs/MOBILE.md`](docs/MOBILE.md).
+
 A store's reads are synchronous — a use case reads its context where a gesture starts and never
 waits for it — so an asynchronous storage is held in memory and written through.
 

package/dist/client/memory.js

@@ -1,13 +1,15 @@
 import { TransportError, } from "./transport.js";
-import { readValues, valuesOf } from "../common/serialization.js";
+import { pack, readValues } from "../common/serialization.js";
 import { answer, answerGroups } from "@sincpro/criteria/engine";
 /**
- * A deep copy written and read by the wire's rules (`valuesOf`, `readValues`): what a real server
+ * A deep copy written and read by the wire's rules (`pack`, `readValues`): what a real server
  * would have received and answered — a `Money` as `{ amount, currency }`, a `Decimal` as its text,
  * a `Date` as an instant, bytes as bytes — the same on every platform. `structuredClone` kept a
  * `Date` a `Date` in a browser and a JSON round trip made it text on a phone; neither is a wire.
  */
-const copyOf = (value) => value === undefined ? value : readValues(valuesOf(value));
+const copyOf = (value) => 
+// Through text, as a wire is: an answer that is a string («"2.50"», an instant) stays one.
+value === undefined ? value : readValues(pack(value));
 function wait(ms, signal) {
     if (ms <= 0)
         return Promise.resolve();

package/dist/codegen/check.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The import rules of a Sincpro application, checked — what `sincpro-client check` runs in an
+ * application's `make doctor`, on the web and on a phone alike.
+ *
+ *     src/domains/<bounded context>/{generated,domain,adapters,services,infrastructure,components,entrypoints}
+ *     src/domains/common/            what bounded contexts share
+ *     src/entrypoints/               where the outside comes in
+ *
+ * | Layer             | Never                                                                  |
+ * | ----------------- | ---------------------------------------------------------------------- |
+ * | generated, domain | React, the DOM's libraries (web-ui, composer), its own adapters        |
+ * | adapters          | React, web-ui, composer                                                |
+ * | services          | React, web-ui, composer                                                |
+ * | infrastructure    | its own components                                                     |
+ * | components        | composer, a router                                                     |
+ * | common            | any bounded context                                                    |
+ * | any layer         | another bounded context — but its `index.ts`, from `infrastructure/`   |
+ * | entrypoints/ root | a bounded context's insides — only its `index.ts` (and `common`)       |
+ *
+ * Context: the architecture says these rules are enforced, not recommended; a rule only read in a
+ * page is the first to go under a deadline. Each import is resolved the way the application's
+ * compiler resolves it — its own `tsconfig.json`, its path aliases (`@/domains/…`) — with the
+ * application's TypeScript, so a relative path and an alias are the same import. Nothing here is
+ * a platform's: a React Native app has the same layers (`react-native` counts as React).
+ */
+export type Violation = {
+    /** The importing file, from the root. */
+    file: string;
+    /** What it imports, as written. */
+    imports: string;
+    why: string;
+};
+/** Where a file is in the application's tree. */
+export type Place = {
+    kind: "context";
+    context: string;
+    layer: string | null;
+    index: boolean;
+} | {
+    kind: "entrypoint";
+} | {
+    kind: "other";
+};
+/**
+ * `domains/sales/services/close.ts` → the bounded context `sales`, the layer `services` — wherever
+ * the `domains/` folder is (`src/domains/…`, a workspace's `domains/sales/src/services/…`).
+ */
+export declare function placeOf(path: string): Place;
+/**
+ * Why `from` may not import `specifier`, which resolves to `to` (`null`: a package), or nothing
+ * when it may.
+ */
+export declare function violationOf(from: Place, specifier: string, to: Place | null): string | undefined;
+/** What stops the check before it starts: no root, no config, a config that does not parse. */
+export declare class CheckError extends Error {
+}
+/**
+ * Every import under `root` that breaks a rule, resolved by the application's own TypeScript and
+ * `tsconfig` (its path aliases and its references included). An alias that does not resolve is a
+ * break too — read as a package it would switch every rule off.
+ */
+export declare function checkImports(root: string, options?: {
+    tsconfig?: string;
+}): Promise<Violation[]>;

package/dist/codegen/check.js

@@ -0,0 +1,195 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+const LAYERS = new Set([
+    "generated",
+    "domain",
+    "adapters",
+    "services",
+    "infrastructure",
+    "components",
+    "entrypoints",
+]);
+/**
+ * `domains/sales/services/close.ts` → the bounded context `sales`, the layer `services` — wherever
+ * the `domains/` folder is (`src/domains/…`, a workspace's `domains/sales/src/services/…`).
+ */
+export function placeOf(path) {
+    const parts = path.split(/[\\/]/).filter((one) => one !== "");
+    const start = parts[0] === "src" ? 1 : 0;
+    if (parts[start] === "entrypoints")
+        return { kind: "entrypoint" };
+    const at = parts.indexOf("domains");
+    const context = at === -1 ? undefined : parts[at + 1];
+    if (context === undefined || parts.length < at + 3)
+        return { kind: "other" };
+    // A bounded context that is a package of its own keeps its code under `src/`.
+    const rest = parts.slice(at + 2);
+    const inside = rest[0] === "src" && rest.length > 1 ? rest.slice(1) : rest;
+    const first = inside[0] ?? "";
+    const index = inside.length === 1 && /^index\.(ts|tsx|js|jsx|mts)$/.test(first);
+    return { kind: "context", context, layer: LAYERS.has(first) ? first : null, index };
+}
+const REACT = /^(react|react-dom|react-native)(\/|$)/;
+const DRAWING = /^@sincpro\/(web-ui|web-composer)(\/|$)/;
+const COMPOSER = /^@sincpro\/web-composer(\/|$)/;
+const ROUTER = /^(react-router|react-router-dom|@tanstack\/react-router|next\/navigation|next\/router|expo-router)(\/|$)/;
+/** web-framework draws; only its `core` is plain logic a service may use. */
+const SCREENS = /^@sincpro\/web-framework(?!\/core(\/|$))(\/|$)/;
+const PLAIN = new Set(["generated", "domain", "adapters", "services"]);
+/** Within a bounded context, what each layer never imports of its own. */
+const NEVER_OWN = {
+    generated: ["adapters", "services", "infrastructure", "components", "entrypoints"],
+    domain: ["adapters", "services", "infrastructure", "components", "entrypoints"],
+    adapters: ["services", "components", "entrypoints"],
+    services: ["components", "entrypoints"],
+    infrastructure: ["components", "entrypoints"],
+};
+/**
+ * Why `from` may not import `specifier`, which resolves to `to` (`null`: a package), or nothing
+ * when it may.
+ */
+export function violationOf(from, specifier, to) {
+    if (to === null) {
+        if (from.kind !== "context" || from.layer === null)
+            return undefined;
+        if (PLAIN.has(from.layer) &&
+            (REACT.test(specifier) || DRAWING.test(specifier) || SCREENS.test(specifier)))
+            return `${from.layer}/ is plain logic: it never imports a screen's library (React, web-ui, composer, web-framework but its core)`;
+        if (from.layer === "components" && (COMPOSER.test(specifier) || ROUTER.test(specifier)))
+            return "a component never decides where things open: no composer, no router";
+        return undefined;
+    }
+    // The application's entrypoints compose everything; nothing imports them back.
+    if (to.kind === "entrypoint")
+        return from.kind === "entrypoint"
+            ? undefined
+            : "nothing imports the application's entrypoints";
+    if (to.kind !== "context")
+        return undefined;
+    // Outside the bounded contexts (the entrypoints, `main.tsx`, a `lib/`): only their index.ts.
+    if (from.kind !== "context")
+        return to.context === "common" || to.index
+            ? undefined
+            : `outside a bounded context, it is used through its index.ts, never its insides («${to.context}»)`;
+    if (from.context === "common")
+        return to.context === "common" ? undefined : "common never imports a bounded context";
+    if (to.context === "common")
+        return undefined;
+    if (to.context === from.context) {
+        const never = from.layer === null ? undefined : NEVER_OWN[from.layer];
+        return to.layer !== null && never?.includes(to.layer) === true
+            ? `${from.layer}/ never imports its own ${to.layer}/`
+            : undefined;
+    }
+    if (to.index && from.layer === "infrastructure")
+        return undefined;
+    return to.index
+        ? `another bounded context («${to.context}») is a dependency: added in infrastructure/, never imported here`
+        : `a bounded context never imports another's insides («${to.context}»): only its index.ts, from infrastructure/`;
+}
+function sources(root) {
+    const found = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name.startsWith("."))
+            continue;
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            found.push(...sources(path));
+        else if (/\.(ts|tsx|mts|cts|js|jsx)$/.test(entry.name) && !entry.name.endsWith(".d.ts"))
+            found.push(path);
+    }
+    return found;
+}
+/** What stops the check before it starts: no root, no config, a config that does not parse. */
+export class CheckError extends Error {
+}
+/**
+ * The compiler options the application resolves with: its config's, and those of every config it
+ * references — Vite writes `files: []` in `tsconfig.json` and keeps its aliases in
+ * `tsconfig.app.json`.
+ */
+function optionsOf(ts, path, seen) {
+    if (seen.has(path))
+        return [];
+    seen.add(path);
+    const read = ts.readConfigFile(path, ts.sys.readFile);
+    if (read.error !== undefined)
+        throw new CheckError(`${path}: ${ts.flattenDiagnosticMessageText(read.error.messageText, " ")}`);
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(path), undefined, path);
+    // «No inputs were found» is what a config of references only says: not an error here.
+    const broken = parsed.errors.find((one) => one.category === ts.DiagnosticCategory.Error && one.code !== 18003);
+    if (broken !== undefined)
+        throw new CheckError(`${path}: ${ts.flattenDiagnosticMessageText(broken.messageText, " ")}`);
+    return [
+        parsed.options,
+        ...(parsed.projectReferences ?? []).flatMap((one) => optionsOf(ts, ts.resolveProjectReferencePath(one), seen)),
+    ];
+}
+/** A style, an image, a font, data: what a bundler loads and TypeScript does not resolve. */
+const ASSET = /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|json|md|mdx)(\?.*)?$/;
+/** `@acme/ventas`, `ventas` — a package named whole, never a path inside it. */
+const BARE = /^(@[^/]+\/)?[^/.@][^/]*$/;
+/**
+ * Every import under `root` that breaks a rule, resolved by the application's own TypeScript and
+ * `tsconfig` (its path aliases and its references included). An alias that does not resolve is a
+ * break too — read as a package it would switch every rule off.
+ */
+export async function checkImports(root, options = {}) {
+    if (!existsSync(root))
+        throw new CheckError(`${root} does not exist: say where the application's code is (--root)`);
+    const { default: ts } = await import("typescript");
+    if (options.tsconfig !== undefined && !ts.sys.fileExists(options.tsconfig))
+        throw new CheckError(`${options.tsconfig} does not exist`);
+    const configPath = options.tsconfig ?? ts.findConfigFile(root, ts.sys.fileExists);
+    const compilers = configPath === undefined ? [{}] : optionsOf(ts, configPath, new Set());
+    const aliases = compilers
+        .flatMap((one) => Object.keys(one.paths ?? {}))
+        .map((pattern) => pattern.replace(/\*.*$/, ""))
+        .filter((prefix) => prefix !== "");
+    const own = (path) => {
+        const from = relative(root, path);
+        return !from.startsWith("..") && !from.split(sep).includes("node_modules");
+    };
+    const violations = [];
+    for (const file of sources(root)) {
+        const name = relative(root, file).split(sep).join("/");
+        const from = placeOf(name);
+        for (const { fileName: specifier } of ts.preProcessFile(readFileSync(file, "utf8"), true, true).importedFiles) {
+            if (ASSET.test(specifier))
+                continue;
+            // The first config that finds it inside the application, else any that finds it.
+            let resolved;
+            for (const compiler of compilers) {
+                const found = ts.resolveModuleName(specifier, file, compiler, ts.sys).resolvedModule;
+                if (found === undefined)
+                    continue;
+                resolved ??= found;
+                if (own(found.resolvedFileName)) {
+                    resolved = found;
+                    break;
+                }
+            }
+            if (resolved === undefined && aliases.some((prefix) => specifier.startsWith(prefix))) {
+                violations.push({
+                    file: name,
+                    imports: specifier,
+                    why: "it does not resolve: an alias of the application that no tsconfig finds",
+                });
+                continue;
+            }
+            const inside = resolved !== undefined && own(resolved.resolvedFileName);
+            let to = inside
+                ? placeOf(relative(root, resolved.resolvedFileName).split(sep).join("/"))
+                : specifier.startsWith(".")
+                    ? { kind: "other" }
+                    : null;
+            // A bounded context that is a package, named whole (`@acme/ventas`): its index.
+            if (to?.kind === "context" && BARE.test(specifier))
+                to = { ...to, index: true };
+            const why = violationOf(from, specifier, to);
+            if (why !== undefined)
+                violations.push({ file: name, imports: specifier, why });
+        }
+    }
+    return violations;
+}

package/dist/codegen/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CheckError, checkImports } from "./check.js";
 import { clientFileOf } from "./client.js";
 import { domainFileOf } from "./domain.js";
 import { entitiesFileOf } from "./entities.js";
 import { aliasOf } from "./names.js";
+import { scaffoldFilesOf } from "./scaffold.js";
 /**
  * `sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]` — what an
  * application's `make client` runs, once per bounded context, over the client contract
@@ -21,7 +23,11 @@ import { aliasOf } from "./names.js";
  * verify-client` regenerates and fails on any difference. The folder is the generator's: keep
  * it out of the application's prettier and eslint, or a formatter rewrites what was generated.
  */
-const USAGE = "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]";
+const USAGE = [
+    "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]",
+    "       sincpro-client scaffold <contract.json> --out <dir> [--transport <module>]",
+    "       sincpro-client check [--root src] [--tsconfig tsconfig.json]",
+].join("\n");
 /** JSON with every key sorted: the snapshot reads the same however the server ordered it. */
 function canonical(value) {
     if (Array.isArray(value))
@@ -35,7 +41,7 @@ function canonical(value) {
 /** The command, its source and its flags — or `undefined` when they do not read as usage says. */
 function parsed(args) {
     const [command, source, ...rest] = args;
-    if (command !== "generate" || source === undefined)
+    if ((command !== "generate" && command !== "scaffold") || source === undefined)
         return undefined;
     const flags = new Map();
     for (let at = 0; at < rest.length; at += 2) {
@@ -46,20 +52,73 @@ function parsed(args) {
         flags.set(flag, value);
     }
     const out = flags.get("--out");
-    const known = new Set(["--out", "--domain", "--base"]);
+    const known = new Set(command === "generate" ? ["--out", "--domain", "--base"] : ["--out", "--transport"]);
     if (out === undefined || [...flags.keys()].some((one) => !known.has(one)))
         return undefined;
     const domain = flags.get("--domain");
     const base = flags.get("--base");
     return {
+        command,
         source,
         out,
         options: {
             ...(domain === undefined ? {} : { domain }),
             ...(base === undefined ? {} : { base }),
         },
+        transport: flags.get("--transport"),
     };
 }
+/** The skeleton, each file only when it is not there: what is there is the application's. */
+function scaffold(metamodel, out, transport) {
+    const files = scaffoldFilesOf(metamodel, transport === undefined ? {} : { transport });
+    const written = [];
+    const kept = [];
+    for (const [name, source] of Object.entries(files)) {
+        const path = join(out, name);
+        if (existsSync(path)) {
+            kept.push(name);
+            continue;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, source);
+        written.push(name);
+    }
+    console.log(`✓ ${aliasOf(metamodel)} → ${out}: written ${written.join(", ") || "nothing"}${kept.length === 0 ? "" : `; kept, already yours: ${kept.join(", ")}`}`);
+    return 0;
+}
+/** The import rules (`codegen/check.ts`): every break said, and a failing exit when any. */
+async function check(args) {
+    const flags = new Map();
+    for (let at = 0; at < args.length; at += 2) {
+        const flag = args[at];
+        const value = args[at + 1];
+        if (flag === undefined ||
+            value === undefined ||
+            !["--root", "--tsconfig"].includes(flag)) {
+            console.error(USAGE);
+            return 2;
+        }
+        flags.set(flag, value);
+    }
+    const root = flags.get("--root") ?? "src";
+    const tsconfig = flags.get("--tsconfig");
+    let found;
+    try {
+        found = await checkImports(root, tsconfig === undefined ? {} : { tsconfig });
+    }
+    catch (error) {
+        if (!(error instanceof CheckError))
+            throw error;
+        console.error(`✘ ${error.message}`);
+        return 2;
+    }
+    for (const one of found)
+        console.error(`✘ ${root}/${one.file} imports "${one.imports}": ${one.why}`);
+    if (found.length > 0)
+        return 1;
+    console.log(`✓ ${root}: every import keeps the layers`);
+    return 0;
+}
 function main(args) {
     const asked = parsed(args);
     if (asked === undefined) {
@@ -67,6 +126,8 @@ function main(args) {
         return 2;
     }
     const metamodel = JSON.parse(readFileSync(asked.source, "utf8"));
+    if (asked.command === "scaffold")
+        return scaffold(metamodel, asked.out, asked.transport);
     const files = { "domain.ts": domainFileOf(metamodel) };
     if (metamodel.bindings !== undefined) {
         files["client.ts"] = clientFileOf(metamodel, asked.options);
@@ -79,4 +140,10 @@ function main(args) {
     console.log(`✓ ${aliasOf(metamodel)} → ${asked.out} (${Object.keys(files).join(", ")})`);
     return 0;
 }
-process.exitCode = main(process.argv.slice(2));
+const args = process.argv.slice(2);
+if (args[0] === "check")
+    void check(args.slice(1)).then((code) => {
+        process.exitCode = code;
+    });
+else
+    process.exitCode = main(args);

package/dist/codegen/client.js

@@ -1,4 +1,4 @@
-import { aliasOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "./names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /**
  * The client of a bounded context as TypeScript: every operation as data, and a method for each
@@ -71,7 +71,7 @@ function dataOf(metamodel, identity, operation, rest) {
         lines.push(`    mcp: { tool: ${JSON.stringify(mcp.tool)} },`);
     return `  ${localOf(metamodel, identity)}: {\n${lines.join("\n")}\n  },`;
 }
-function methodSourceOf(local, method, call, rest, doc) {
+function methodSourceOf(local, answer, method, call, rest, doc) {
     if (call.kind === "list") {
         const entity = `dto.${identifierOf(call.entity)}`;
         const params = paramsOf(call);
@@ -80,7 +80,7 @@ function methodSourceOf(local, method, call, rest, doc) {
     }
     if (call.kind === "read") {
         const params = paramsOf(call);
-        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${local}Answer>(transport, ${params.route(rest.path)}),`;
+        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${answer}>(transport, ${params.route(rest.path)}),`;
     }
     if (call.kind === "one") {
         const path = rest.path.replace(`{${call.field}}`, "${encodeURIComponent(id)}");
@@ -91,7 +91,7 @@ function methodSourceOf(local, method, call, rest, doc) {
         : "undefined";
     return [
         `${doc}    ${method}: (body: dto.${local}, options?: SendOptions) =>`,
-        `      transport.send<dto.${local}Answer>(`,
+        `      transport.send<dto.${answer}>(`,
         `        ${JSON.stringify(rest.method)},`,
         `        pathFor(routes.${method}, ${id}, body),`,
         `        body,`,
@@ -134,7 +134,7 @@ export function clientFileOf(metamodel, options = {}) {
         const method = methodOf(local);
         claim(method, `operation ${identity}`);
         const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
-        methods.push(methodSourceOf(local, method, call, rest, doc));
+        methods.push(methodSourceOf(local, answerOf(metamodel, identity), method, call, rest, doc));
         if (call.kind === "list" || call.kind === "read") {
             paged ||= call.kind === "list";
             reads ||= call.kind === "read";

package/dist/codegen/domain.d.ts

@@ -4,7 +4,8 @@ import type { Metamodel } from "./metamodel.js";
  *
  * 1. The models, by name: an entity's contract, a related model by its own name.
  * 2. Each operation, by its local name (its identity without `<context>.`): its input as
- *    `<Name>` and its answer as `<Name>Answer`.
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
+ *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
  * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
  *    never one a package of the stack already types (`Criteria`).
  * Final: a header that says where it came from and not to edit it, the imports, then models,

package/dist/codegen/domain.js

@@ -1,4 +1,4 @@
-import { claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
+import { answerOf, claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
 /**
  * The DTOs of a bounded context as TypeScript, out of the contract sincpro_framework exports:
  * a type per model, per shared definition a model or an operation reaches, and per operation's
@@ -150,7 +150,8 @@ function operationDoc(metamodel, local, operation) {
  *
  * 1. The models, by name: an entity's contract, a related model by its own name.
  * 2. Each operation, by its local name (its identity without `<context>.`): its input as
- *    `<Name>` and its answer as `<Name>Answer`.
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
+ *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
  * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
  *    never one a package of the stack already types (`Criteria`).
  * Final: a header that says where it came from and not to edit it, the imports, then models,
@@ -165,15 +166,26 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `model ${name}`);
         return `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, true)};`;
     });
+    // A Response two Commands share is written once, under the first that answers with it.
+    const answered = new Set();
     const operations = sorted(metamodel.operations).flatMap(([identity, operation]) => {
         const local = localOf(metamodel, identity);
+        const named = answerOf(metamodel, identity);
         claim(local, `operation ${identity}`);
-        claim(`${local}Answer`, `the answer of ${identity}`);
         const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
-        return [
+        const written = [
             `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
-            `/** What \`${local}\` answers. */\nexport type ${local}Answer = ${answer};`,
         ];
+        if (!answered.has(named)) {
+            answered.add(named);
+            claim(named, `the answer of ${identity}`);
+            written.push(`/** What \`${local}\` answers. */\nexport type ${named} = ${answer};`);
+        }
+        if (named !== `${local}Answer`) {
+            claim(`${local}Answer`, `the old name of the answer of ${identity}`);
+            written.push(`/** @deprecated The backend calls it \`${named}\`: use that name. */\nexport type ${local}Answer = ${named};`);
+        }
+        return written;
     });
     const written = new Map();
     for (let pending = [...scope.reached]; pending.length > 0;) {

package/dist/codegen/entities.js

@@ -1,5 +1,5 @@
 import { entityKeyOf } from "../client/contract.js";
-import { aliasOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /** The one operation of `role` for `entity` a transport can call, by `own` when there are many. */
 function oneOf(candidates, role) {
@@ -37,7 +37,14 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const rest = restOf(metamodel, identity, options);
         return rest === undefined
             ? []
-            : [{ local: localOf(metamodel, identity), operation, rest }];
+            : [
+                {
+                    local: localOf(metamodel, identity),
+                    answer: answerOf(metamodel, identity),
+                    operation,
+                    rest,
+                },
+            ];
     });
     const reads = (role, method) => reached.filter((one) => one.operation.role === role &&
         method(one.rest.method) &&
@@ -88,7 +95,7 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         bodies.push(target === undefined
             ? `    ${method}: dto.${command.local};`
             : `    ${method}: Omit<dto.${command.local}, ${JSON.stringify(target)}>;`);
-        answers.push(`    ${method}: dto.${command.local}Answer;`);
+        answers.push(`    ${method}: dto.${command.answer};`);
         named.push(target === undefined
             ? `    ${method}: ${JSON.stringify(route)},`
             : `    ${method}: { route: ${JSON.stringify(route)}, target: ${JSON.stringify(target)} },`);

package/dist/codegen/index.d.ts

@@ -3,8 +3,10 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
+export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./check.js";
 export { clientFileOf } from "./client.js";
 export { domainFileOf } from "./domain.js";
 export { entitiesFileOf } from "./entities.js";
 export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./metamodel.js";
 export type { GenerateOptions } from "./rest.js";
+export { scaffoldFilesOf, type ScaffoldOptions, } from "./scaffold.js";

package/dist/codegen/index.js

@@ -3,6 +3,8 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
+export { CheckError, checkImports, placeOf, violationOf, } from "./check.js";
 export { clientFileOf } from "./client.js";
 export { domainFileOf } from "./domain.js";
 export { entitiesFileOf } from "./entities.js";
+export { scaffoldFilesOf, } from "./scaffold.js";

package/dist/codegen/names.d.ts

@@ -21,6 +21,18 @@ export declare function aliasOf(metamodel: Metamodel): string;
 export declare function isEntity(metamodel: Metamodel, model: string): boolean;
 /** An operation's name in its context: its identity without `<bounded_context>.`. */
 export declare function localOf(metamodel: Metamodel, identity: string): string;
+/**
+ * What an operation's answer is called: the backend's own name for it — its output's title,
+ * `ResponseCancelIssue` — when that name is one type (every output with it is the same schema)
+ * and no other type has it; `<Name>Answer` when the output has no name of its own (a model, a
+ * list) or two different shapes share it. A new operation answering with the same Response keeps
+ * the name: regenerating never renames by itself.
+ *
+ * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
+ * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
+ * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ */
+export declare function answerOf(metamodel: Metamodel, identity: string): string;
 /** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
 export declare function methodOf(local: string): string;
 /** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */