@sincpro/client-framework 0.0.0-stage → 0.2.0

package/dist/codegen/client.js

@@ -0,0 +1,180 @@
+import { aliasOf, 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
+ * one REST reaches the way a `Transport` sends — over `@sincpro/client-framework`, so a script,
+ * a test or a hook of its own calls the service typed, with no screen.
+ *
+ * Context: a method only writes down the route the contract published and hands the call to the
+ * transport, which keeps the rules — the `Idempotency-Key`, the `Problem`, the model's version.
+ * A GET is a page (`list`), one record (`one`), or — a Query of the context's own, `GET /me` —
+ * a read of its answer as it came (`readRoute`, over a transport that has `read`). A GET's
+ * keys in its path are required parameters; every other field is an optional one.
+ */
+/** A search's fields a page asks with, not the screen: the criteria, and its cursor inside it. */
+const PAGED = new Set(["criteria", "cursor"]);
+/** A GET's parameters: the path's keys, and the rest of its input but what a page asks with. */
+function askedOf(operation, rest, paged) {
+    const path = [...rest.fields].sort();
+    const query = Object.keys(operation.input.properties ?? {})
+        .filter((one) => !path.includes(one) && !(paged && PAGED.has(one)))
+        .sort();
+    return { path, query };
+}
+function callOf(metamodel, operation, rest) {
+    if (rest === undefined)
+        return { kind: "none", why: "REST does not publish it" };
+    if (WRITES.has(rest.method))
+        return { kind: "send" };
+    const owner = ownerOf(metamodel, operation);
+    if (operation.role === "search" && owner !== undefined && owner in metamodel.models)
+        return { kind: "list", entity: owner, ...askedOf(operation, rest, true) };
+    const field = owner === undefined ? undefined : operation.targets[owner];
+    const record = rest.fields.length === 1 && rest.fields[0] === field;
+    if (operation.role === "get" && owner !== undefined && field !== undefined && record)
+        return { kind: "one", entity: owner, field };
+    // Any other GET — a Query of the context's own, `GET /me` — is read as it answers.
+    return { kind: "read", ...askedOf(operation, rest, false) };
+}
+/** A parameter list's TypeScript: the path's keys required, the rest optional, all as text. */
+function paramsOf(asked) {
+    const union = (names) => names.map((one) => JSON.stringify(one)).join(" | ");
+    if (asked.path.length === 0 && asked.query.length === 0)
+        return { signature: "", route: (path) => JSON.stringify(path) };
+    const required = asked.path.length === 0 ? "" : `Readonly<Record<${union(asked.path)}, string>>`;
+    const optional = asked.query.length === 0 ? "" : `Partial<Record<${union(asked.query)}, string>>`;
+    const type = [required, optional].filter((one) => one !== "").join(" & ");
+    return {
+        signature: `params${asked.path.length === 0 ? "?" : ""}: ${type}`,
+        route: (path) => `listRoute(${JSON.stringify(path)}, params)`,
+    };
+}
+/** The data of one operation: what it is, and how each wire reaches it. */
+function dataOf(metamodel, identity, operation, rest) {
+    const lines = [
+        `    identity: ${JSON.stringify(identity)},`,
+        `    role: ${JSON.stringify(operation.role)},`,
+        `    query: ${operation.query},`,
+        `    entities: ${JSON.stringify(operation.entities)},`,
+        `    targets: ${recordLiteral(operation.targets)},`,
+    ];
+    if (rest !== undefined)
+        lines.push(`    rest: { method: ${JSON.stringify(rest.method)}, path: ${JSON.stringify(rest.path)} },`);
+    const rpc = metamodel.bindings?.rpc?.[identity];
+    if (rpc !== undefined)
+        lines.push(`    rpc: { method: ${JSON.stringify(rpc.method)} },`);
+    const grpc = metamodel.bindings?.grpc?.[identity];
+    if (grpc !== undefined)
+        lines.push(`    grpc: { method: ${JSON.stringify(grpc.method)} },`);
+    const mcp = metamodel.bindings?.mcp?.[identity];
+    if (mcp !== undefined)
+        lines.push(`    mcp: { tool: ${JSON.stringify(mcp.tool)} },`);
+    return `  ${localOf(metamodel, identity)}: {\n${lines.join("\n")}\n  },`;
+}
+function methodSourceOf(local, method, call, rest, doc) {
+    if (call.kind === "list") {
+        const entity = `dto.${identifierOf(call.entity)}`;
+        const params = paramsOf(call);
+        const signature = params.signature === "" ? "" : `, ${params.signature}`;
+        return `${doc}    ${method}: (criteria: Criteria<${entity}>${signature}) =>\n      transport.list<${entity}>(${params.route(rest.path)}, criteria),`;
+    }
+    if (call.kind === "read") {
+        const params = paramsOf(call);
+        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${local}Answer>(transport, ${params.route(rest.path)}),`;
+    }
+    if (call.kind === "one") {
+        const path = rest.path.replace(`{${call.field}}`, "${encodeURIComponent(id)}");
+        return `${doc}    ${method}: (id: string) =>\n      transport.one<dto.${identifierOf(call.entity)}>(\`${path}\`),`;
+    }
+    const id = rest.fields.includes("id")
+        ? "body.id === undefined ? undefined : String(body.id)"
+        : "undefined";
+    return [
+        `${doc}    ${method}: (body: dto.${local}, options?: SendOptions) =>`,
+        `      transport.send<dto.${local}Answer>(`,
+        `        ${JSON.stringify(rest.method)},`,
+        `        pathFor(routes.${method}, ${id}, body),`,
+        `        body,`,
+        `        undefined,`,
+        `        options,`,
+        `      ),`,
+    ].join("\n");
+}
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets
+ *    and the binding of each wire that publishes it.
+ * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
+ *    — or none, said in the client's own doc.
+ * 3. The routes of the writes, read once (`writeRoute`).
+ * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
+ *    one name are refused, naming both.
+ */
+export function clientFileOf(metamodel, options = {}) {
+    const claim = claimed();
+    const operations = sorted(metamodel.operations);
+    const data = [];
+    const routes = [];
+    const methods = [];
+    const unreached = [];
+    let lists = false;
+    let paged = false;
+    let reads = false;
+    let sends = false;
+    for (const [identity, operation] of operations) {
+        const local = localOf(metamodel, identity);
+        const rest = restOf(metamodel, identity, options);
+        data.push(dataOf(metamodel, identity, operation, rest));
+        const call = callOf(metamodel, operation, rest);
+        if (call.kind === "none" || rest === undefined) {
+            unreached.push(`\`${local}\`: ${call.kind === "none" ? call.why : ""}.`);
+            continue;
+        }
+        const method = methodOf(local);
+        claim(method, `operation ${identity}`);
+        const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
+        methods.push(methodSourceOf(local, method, call, rest, doc));
+        if (call.kind === "list" || call.kind === "read") {
+            paged ||= call.kind === "list";
+            reads ||= call.kind === "read";
+            lists ||= call.path.length + call.query.length > 0;
+        }
+        if (call.kind === "send") {
+            sends = true;
+            routes.push(`  ${method}: writeRoute(${JSON.stringify(`${rest.method} ${rest.path}`)}),`);
+        }
+    }
+    const core = [
+        "bindable",
+        ...(lists ? ["listRoute"] : []),
+        ...(sends ? ["pathFor"] : []),
+        ...(reads ? ["readRoute"] : []),
+        ...(sends ? ["type SendOptions"] : []),
+        "type Transport",
+        ...(sends ? ["writeRoute"] : []),
+    ];
+    const imports = [
+        ...(paged ? ['import type { Criteria } from "@sincpro/criteria";'] : []),
+        `import { ${core.join(", ")} } from "${FRAMEWORK}";`,
+        "",
+        `import type * as dto from "${DOMAIN_MODULE}";`,
+    ].join("\n");
+    const client = [
+        "/**",
+        ` * «${aliasOf(metamodel)}» over a transport: a method for each operation REST reaches as a`,
+        " * page, a record, a read of its own or a write. Used by a Feature, each request carries the",
+        " * trace and the context of the use case that sent it (`bindable`).",
+        ...(unreached.length === 0
+            ? []
+            : [" *", " * Without a method here:", ...unreached.map((one) => ` * - ${one}`)]),
+        " */",
+    ].join("\n");
+    return `${[
+        headerOf("The client", metamodel),
+        imports,
+        `/** Every operation of «${aliasOf(metamodel)}», as data: what it is, and how each wire reaches it. */\nexport const operations = {\n${data.join("\n")}\n} as const;`,
+        ...(routes.length === 0 ? [] : [`const routes = {\n${routes.join("\n")}\n};`]),
+        `${client}\nexport function clientOf(transport: Transport) {\n  return bindable(transport, (transport) => ({\n${methods.join("\n")}\n  }));\n}`,
+    ].join("\n\n")}\n`;
+}

package/dist/codegen/domain.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+/**
+ * The TypeScript of every DTO of `metamodel`, as the text of one file.
+ *
+ * 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`.
+ * 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,
+ *    definitions and operations, each sorted by name; two of them with one TypeScript name are
+ *    refused, naming both.
+ */
+export declare function domainFileOf(metamodel: Metamodel): string;

package/dist/codegen/domain.js

@@ -0,0 +1,195 @@
+import { 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
+ * input and answer. Only types — nothing in the file runs.
+ *
+ * Context: the file is a snapshot for whoever writes code — a person, or an agent reading the
+ * repository —, never the truth at runtime: the transport keeps reading the live definition and
+ * revalidates it by `model_version`. So it is written the same way for the same contract (every
+ * key sorted, byte for byte, which is what `make verify-client` compares) and never edited; an
+ * application extends a type by composition (`Wire & {…}`).
+ *
+ * criteria's grammar comes with every metamodel (`$defs.Criteria`); `@sincpro/criteria` already
+ * types it, so it is imported, never written a second time.
+ *
+ *     domainFileOf(JSON.parse(readFileSync("project.contract.json", "utf8")))
+ */
+const MODELS = "#/models/";
+const DEFINITIONS = "#/$defs/";
+/** A shared definition a package of the stack already types: imported, never written again. */
+const IMPORTED = {
+    Criteria: { name: "Criteria", from: "@sincpro/criteria" },
+};
+/** The field types whose value is the record itself, not a key that names it. */
+const RELATIONAL = new Set(["many2one", "one2many", "many2many", "embedded"]);
+/** A related record: in an answer only when the read expands it. */
+const EXPANDED = new Set(["many2one", "one2many", "many2many"]);
+const SIMPLE_TYPE = /^[A-Za-z0-9_$.]+$/;
+function union(members) {
+    const distinct = [...new Set(members)];
+    if (distinct.includes("unknown"))
+        return "unknown";
+    return distinct.join(" | ");
+}
+function arrayOf(item) {
+    return SIMPLE_TYPE.test(item) ? `${item}[]` : `Array<${item}>`;
+}
+/** Whose record a key names — `EntityID[Customer]` on the server —, said where it is written. */
+function keyNote(schema) {
+    const said = schema["x-sincpro"];
+    if (said?.relation == null || RELATIONAL.has(said.type ?? ""))
+        return undefined;
+    return `The key of a \`${said.relation}\`.`;
+}
+function scopeOf(metamodel) {
+    const definitions = metamodel.$defs ?? {};
+    const scope = {
+        reached: new Set(),
+        imports: new Set(),
+        refer: (ref) => {
+            const model = ref.startsWith(MODELS);
+            if (!model && !ref.startsWith(DEFINITIONS))
+                throw new Error(`"${ref}" points outside the metamodel of ${contextOf(metamodel)}`);
+            const name = ref.slice(model ? MODELS.length : DEFINITIONS.length);
+            // A model's own contract names a related model as a definition (`#/$defs/Run`).
+            if (model || name in metamodel.models) {
+                if (!(name in metamodel.models))
+                    throw new Error(`"${ref}" names no model of ${contextOf(metamodel)}`);
+                return identifierOf(name);
+            }
+            const imported = IMPORTED[name];
+            if (imported !== undefined) {
+                scope.imports.add(name);
+                return imported.name;
+            }
+            if (!(name in definitions))
+                throw new Error(`"${ref}" names no definition of ${contextOf(metamodel)}`);
+            scope.reached.add(name);
+            return identifierOf(name);
+        },
+    };
+    return scope;
+}
+/**
+ * Whether a property may be absent. In a record a model describes, every field comes but a
+ * related record, which comes only when the read expands it: the server writes the whole record,
+ * and its contract lists as required only what has no default (most fields have one). Anywhere
+ * else — an operation's input or answer, a shared definition — `required` says it.
+ */
+function optional(name, property, schema, record) {
+    if (record)
+        return EXPANDED.has(property["x-sincpro"]?.type ?? "");
+    return !(schema.required ?? []).includes(name);
+}
+function objectOf(schema, scope, depth, record) {
+    const properties = sorted(schema.properties ?? {});
+    if (properties.length === 0) {
+        const extra = schema.additionalProperties;
+        if (extra === false)
+            return "Record<string, never>";
+        const value = extra === undefined || extra === true ? "unknown" : typeOf(extra, scope, depth, record);
+        return `Record<string, ${value}>`;
+    }
+    const pad = "  ".repeat(depth + 1);
+    const lines = properties.map(([name, property]) => {
+        const doc = docOf([property.description, keyNote(property)], pad);
+        const mark = optional(name, property, schema, record) ? "?" : "";
+        return `${doc}${pad}${keyOf(name)}${mark}: ${typeOf(property, scope, depth + 1, record)};`;
+    });
+    return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
+}
+/** The TypeScript of `schema`; `record` when it is (inside) a record a model describes. */
+function typeOf(schema, scope, depth, record) {
+    if (schema.$ref !== undefined)
+        return scope.refer(schema.$ref);
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options !== undefined)
+        return union(options.map((one) => typeOf(one, scope, depth, record)));
+    if ("const" in schema)
+        return JSON.stringify(schema.const);
+    if (schema.enum !== undefined)
+        return union(schema.enum.map((one) => JSON.stringify(one)));
+    const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []);
+    if (types.length > 1)
+        return union(types.map((one) => typeOf({ ...schema, type: one }, scope, depth, record)));
+    switch (types[0]) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array":
+            return arrayOf(schema.items === undefined ? "unknown" : typeOf(schema.items, scope, depth, record));
+        case "object":
+            return objectOf(schema, scope, depth, record);
+        default:
+            return schema.properties === undefined
+                ? "unknown"
+                : objectOf(schema, scope, depth, record);
+    }
+}
+/** What the server says of an operation: its words, then what it is, for whom, on which field. */
+function operationDoc(metamodel, local, operation) {
+    const runsOn = sorted(operation.targets).map(([entity, field]) => `\`${entity}\` in \`${field}\``);
+    const whose = operation.entities.map((one) => `\`${one}\``).join(", ");
+    const facts = [
+        `\`${operation.role}\`${whose === "" ? "" : ` of ${whose}`}`,
+        operation.query ? "reads only" : undefined,
+        operation.dry_run ? "may run dry" : undefined,
+        runsOn.length === 0 ? undefined : `its record: ${runsOn.join(", ")}`,
+    ].filter((one) => one !== undefined);
+    return (docOf([operation.description, `${facts.join(" · ")}.`, deprecationOf(metamodel, operation)], "") || `/** ${local} */\n`);
+}
+/**
+ * The TypeScript of every DTO of `metamodel`, as the text of one file.
+ *
+ * 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`.
+ * 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,
+ *    definitions and operations, each sorted by name; two of them with one TypeScript name are
+ *    refused, naming both.
+ */
+export function domainFileOf(metamodel) {
+    const scope = scopeOf(metamodel);
+    const definitions = metamodel.$defs ?? {};
+    const claim = claimed();
+    const models = sorted(metamodel.models).map(([name, schema]) => {
+        claim(identifierOf(name), `model ${name}`);
+        return `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, true)};`;
+    });
+    const operations = sorted(metamodel.operations).flatMap(([identity, operation]) => {
+        const local = localOf(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 [
+            `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
+            `/** What \`${local}\` answers. */\nexport type ${local}Answer = ${answer};`,
+        ];
+    });
+    const written = new Map();
+    for (let pending = [...scope.reached]; pending.length > 0;) {
+        for (const name of pending) {
+            const schema = definitions[name];
+            written.set(name, `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, false)};`);
+        }
+        pending = [...scope.reached].filter((name) => !written.has(name));
+    }
+    const shared = [...written.keys()].sort().map((name) => {
+        claim(identifierOf(name), `definition ${name}`);
+        return written.get(name);
+    });
+    const imports = [...scope.imports].sort().map((name) => {
+        const imported = IMPORTED[name];
+        return `import type { ${imported.name} } from "${imported.from}";`;
+    });
+    return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
+}

package/dist/codegen/entities.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+import { type GenerateOptions } from "./rest.js";
+/**
+ * The TypeScript of the entities of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
+ *    several) — none, and the model gets no entity, said in the file's own doc.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 3. Every write of role `command` that concerns it: with `target` when its body names the
+ *    record, as it is when it creates one; its body typed without that field.
+ * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of
+ *    them, for `FrameworkProvider entities`.
+ */
+export declare function entitiesFileOf(metamodel: Metamodel, options?: GenerateOptions): string;

package/dist/codegen/entities.js

@@ -0,0 +1,158 @@
+import { entityKeyOf } from "../client/contract.js";
+import { aliasOf, 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) {
+    if (candidates.length === 0)
+        return undefined;
+    if (candidates.length === 1)
+        return { found: candidates[0] };
+    const own = candidates.filter((one) => one.operation.own === true);
+    if (own.length === 1)
+        return { found: own[0] };
+    const names = candidates.map((one) => `\`${one.local}\``).join(", ");
+    return { missing: `${candidates.length} of role \`${role}\` (${names}) and none \`own\`` };
+}
+/** A route for `entity()`: the record's field in the path written `{id}`, as `entity()` fills it. */
+function recordPath(rest, field) {
+    return field === undefined || field === "id"
+        ? rest.path
+        : rest.path.replace(`{${field}}`, "{id}");
+}
+/**
+ * The field of a Command's body that names the one record of `model` it runs on. A list of keys
+ * (`list[EntityID[Issue]]`, `issue_ids`) names many: `run(id, body)` has one id to give, so the
+ * screen sends that list in the body itself.
+ */
+function singleTarget(operation, model) {
+    const field = operation.targets[model];
+    if (field === undefined)
+        return undefined;
+    const schema = operation.input.properties?.[field];
+    const held = schema?.anyOf?.find((one) => one.type !== "null") ?? schema;
+    return held?.type === "array" ? undefined : field;
+}
+function entitySourceOf(metamodel, model, domain, options, claim) {
+    const reached = sorted(metamodel.operations).flatMap(([identity, operation]) => {
+        const rest = restOf(metamodel, identity, options);
+        return rest === undefined
+            ? []
+            : [{ local: localOf(metamodel, identity), operation, rest }];
+    });
+    const reads = (role, method) => reached.filter((one) => one.operation.role === role &&
+        method(one.rest.method) &&
+        ownerOf(metamodel, one.operation) === model);
+    const isGet = (verb) => verb === "GET";
+    const isWrite = (verb) => WRITES.has(verb);
+    const list = oneOf(reads("search", isGet), "search");
+    if (list === undefined)
+        return { missing: "no `search` a transport reads" };
+    if ("missing" in list)
+        return { missing: list.missing };
+    // A list under a record (`/tenants/{tenant_id}/members`) keeps its keys: the screen gives
+    // them as the list's parameters (`useListing(entity, { params })`), and `listRoute` fills them.
+    const missing = [];
+    const routes = [`  list: ${JSON.stringify(list.found.rest.path)},`];
+    const one = oneOf(reads("get", isGet), "get");
+    if (one !== undefined && "found" in one) {
+        const field = one.found.operation.targets[model];
+        if (field !== undefined && one.found.rest.fields.length === 1)
+            routes.push(`  one: ${JSON.stringify(recordPath(one.found.rest, field))},`);
+        else
+            missing.push(`one: \`${one.found.local}\` is at ${one.found.rest.path}`);
+    }
+    else if (one !== undefined)
+        missing.push(`one: ${one.missing}`);
+    for (const role of ["edit", "preview"]) {
+        const write = oneOf(reads(role, isWrite), role);
+        if (write === undefined)
+            continue;
+        if ("missing" in write) {
+            missing.push(`${role}: ${write.missing}`);
+            continue;
+        }
+        const field = write.found.operation.targets[model];
+        const route = `${write.found.rest.method} ${recordPath(write.found.rest, field)}`;
+        routes.push(`  ${role}: ${JSON.stringify(route)},`);
+    }
+    const commands = reached.filter((one) => one.operation.role === "command" &&
+        isWrite(one.rest.method) &&
+        one.operation.entities.includes(model));
+    const bodies = [];
+    const answers = [];
+    const named = [];
+    for (const command of commands) {
+        const method = methodOf(command.local);
+        const target = singleTarget(command.operation, model);
+        const route = `${command.rest.method} ${command.rest.path}`;
+        bodies.push(target === undefined
+            ? `    ${method}: dto.${command.local};`
+            : `    ${method}: Omit<dto.${command.local}, ${JSON.stringify(target)}>;`);
+        answers.push(`    ${method}: dto.${command.local}Answer;`);
+        named.push(target === undefined
+            ? `    ${method}: ${JSON.stringify(route)},`
+            : `    ${method}: { route: ${JSON.stringify(route)}, target: ${JSON.stringify(target)} },`);
+    }
+    if (named.length > 0)
+        routes.push(`  commands: {\n${named.join("\n")}\n  },`);
+    const name = pluralOf(identifierOf(model));
+    claim(name, `the entity of ${model}`);
+    const types = bodies.length === 0
+        ? `dto.${identifierOf(model)}`
+        : `\n  dto.${identifierOf(model)},\n  {\n${bodies.join("\n")}\n  },\n  {\n${answers.join("\n")}\n  }\n`;
+    const doc = [
+        "/**",
+        ` * \`${model}\`: its list, its record and the Commands that run on it or create it.`,
+        ...(missing.length === 0
+            ? []
+            : [" *", " * Not declared:", ...missing.map((one) => ` * - ${one}.`)]),
+        " */",
+    ].join("\n");
+    const key = JSON.stringify(entityKeyOf(domain, model));
+    return {
+        name,
+        missing,
+        source: `${doc}\nexport const ${name} = entity<${types}>(${key}, {\n${routes.join("\n")}\n});`,
+    };
+}
+/**
+ * The TypeScript of the entities of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
+ *    several) — none, and the model gets no entity, said in the file's own doc.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 3. Every write of role `command` that concerns it: with `target` when its body names the
+ *    record, as it is when it creates one; its body typed without that field.
+ * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of
+ *    them, for `FrameworkProvider entities`.
+ */
+export function entitiesFileOf(metamodel, options = {}) {
+    const domain = options.domain ?? aliasOf(metamodel);
+    const claim = claimed();
+    claim("entities", "the list of every entity");
+    const declared = [];
+    const left = [];
+    // A value a record holds (no identity) is no entity: it is never listed nor opened alone.
+    for (const [model] of sorted(metamodel.models).filter(([name]) => isEntity(metamodel, name))) {
+        const one = entitySourceOf(metamodel, model, domain, options, claim);
+        if ("source" in one)
+            declared.push(one);
+        else
+            left.push(`\`${model}\`: ${one.missing}`);
+    }
+    const imports = [
+        `import { entity } from "${FRAMEWORK}";`,
+        "",
+        `import type * as dto from "${DOMAIN_MODULE}";`,
+    ].join("\n");
+    const all = [
+        "/**",
+        ` * Every entity of «${aliasOf(metamodel)}», for \`FrameworkProvider entities\`.`,
+        ...(left.length === 0
+            ? []
+            : [" *", " * Without an entity here:", ...left.map((one) => ` * - ${one}.`)]),
+        " */",
+        `export const entities = [${declared.map((one) => one.name).join(", ")}] as const;`,
+    ].join("\n");
+    return `${[headerOf("The entities", metamodel), imports, ...declared.map((one) => one.source), all].join("\n\n")}\n`;
+}

package/dist/codegen/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The generator: a bounded context's DTOs, client and entities out of the client contract
+ * 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 { 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";

package/dist/codegen/index.js

@@ -0,0 +1,8 @@
+/**
+ * The generator: a bounded context's DTOs, client and entities out of the client contract
+ * 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 { clientFileOf } from "./client.js";
+export { domainFileOf } from "./domain.js";
+export { entitiesFileOf } from "./entities.js";