create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -1,72 +0,0 @@
-package ${base_package}.rest;
-
-${application_service_import}
-${dto_imports}
-${web_convertor_import}
-import ${page_result_type};
-import ${single_result_type};
-import lombok.RequiredArgsConstructor;
-import org.springframework.web.bind.annotation.*;
-import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
-import ${validation_namespace}.validation.Valid;
-
-/**
- * ${domain_desc} 管理
- *
- * @author ${author}
- */
-@RestController
-@RequestMapping("/api/${module_name}/${domain_url_path}")
-@RequiredArgsConstructor
-@Tag(name = "${domain_desc}管理")
-public class ${domain_class}Controller {
-
-    ${application_service_field}
-    private final ${web_convertor_class} webConvertor;
-
-    /**
-     * 分页查询 ${domain_desc}
-     */
-    @PostMapping("/page")
-    @Operation(summary = "分页查询")
-    public ${page_result_simple_name}<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
-        return webConvertor.toResponsePage(${query_call});
-    }
-
-    /**
-     * 根据ID查询 ${domain_desc}
-     */
-    @GetMapping("/{id}")
-    @Operation(summary = "详情查询")
-    public ${single_result_simple_name}<${response_class}> detail(@PathVariable Long id) {
-        return ${single_result_simple_name}.${single_result_factory_method}(webConvertor.toResponse(${detail_call}));
-    }
-
-    /**
-     * 新增 ${domain_desc}
-     */
-    @PostMapping
-    @Operation(summary = "新增")
-    public ${single_result_simple_name}<Long> add(@Valid @RequestBody ${create_request_class} request) {
-        return ${single_result_simple_name}.${single_result_factory_method}(${add_call});
-    }
-
-    /**
-     * 更新 ${domain_desc}
-     */
-    @PutMapping
-    @Operation(summary = "更新")
-    public ${single_result_simple_name}<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
-        return ${single_result_simple_name}.${single_result_factory_method}(${update_call});
-    }
-
-    /**
-     * 删除 ${domain_desc}
-     */
-    @DeleteMapping("/{id}")
-    @Operation(summary = "删除")
-    public ${single_result_simple_name}<Boolean> delete(@PathVariable Long id) {
-        return ${single_result_simple_name}.${single_result_factory_method}(${delete_call});
-    }
-}

package/template/.hermes/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -1,30 +0,0 @@
-package ${base_package}.rest.convertor;
-
-import ${page_result_type};
-${application_type_imports}
-import ${base_package}.rest.dto.request.${domain_class}CreateRequest;
-import ${base_package}.rest.dto.request.${domain_class}UpdateRequest;
-import ${base_package}.rest.dto.request.${domain_class}PageRequest;
-import ${base_package}.rest.dto.response.${domain_class}Response;
-import org.mapstruct.Mapper;
-import java.util.List;
-
-@Mapper(componentModel = "spring")
-public interface ${web_convertor_class} {
-
-    ${domain_class}CreateCommand toCreateCommand(${domain_class}CreateRequest source);
-
-    ${domain_class}UpdateCommand toUpdateCommand(${domain_class}UpdateRequest source);
-
-    ${domain_class}PageQuery toPageQuery(${domain_class}PageRequest source);
-
-    ${domain_class}Response toResponse(${domain_class}Result source);
-
-    List<${domain_class}Response> toResponses(List<${domain_class}Result> source);
-
-    default ${page_result_simple_name}<${domain_class}Response> toResponsePage(${page_result_simple_name}<${domain_class}Result> source) {
-        return ${page_result_simple_name}.${page_result_factory_method}(
-${page_result_factory_arguments}
-        );
-    }
-}

package/template/.hermes/skills/yss-web-controller/assets/templates/web/dto/CreateRequest.java.template

@@ -1,19 +0,0 @@
-package ${base_package}.rest.dto.request;
-
-import ${command_dto_type};
-import lombok.Getter;
-import lombok.Setter;
-import ${validation_namespace}.validation.constraints.NotBlank;
-import ${validation_namespace}.validation.constraints.NotNull;
-import java.util.Date;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-import java.time.LocalDate;
-
-/** ${domain_desc}新增请求。字段来自批准的 OpenAPI allowlist。 */
-@Getter
-@Setter
-public class ${domain_class}CreateRequest extends ${command_dto_simple_name} {
-
-${field_declarations}
-}

package/template/.hermes/skills/yss-web-controller/assets/templates/web/dto/PageRequest.java.template

@@ -1,21 +0,0 @@
-package ${base_package}.rest.dto.request;
-
-import ${query_dto_type};
-import lombok.Getter;
-import lombok.Setter;
-import ${validation_namespace}.validation.constraints.Pattern;
-import java.util.Date;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-import java.time.LocalDate;
-
-/**
- * ${domain_desc}分页请求。仅暴露已冻结的 HTTP 查询字段。
- */
-@Getter
-@Setter
-public class ${domain_class}PageRequest extends ${query_dto_simple_name} {
-${pagination_field_declarations}
-
-${field_declarations}
-}

package/template/.hermes/skills/yss-web-controller/assets/templates/web/dto/Response.java.template

@@ -1,18 +0,0 @@
-package ${base_package}.rest.dto.response;
-
-import lombok.Getter;
-import lombok.Setter;
-import java.io.Serializable;
-import java.util.Date;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-import java.time.LocalDate;
-
-/** ${domain_desc}公开响应。字段来自批准的 OpenAPI allowlist。 */
-@Getter
-@Setter
-public class ${domain_class}Response implements Serializable {
-    private static final long serialVersionUID = 1L;
-
-${field_declarations}
-}

package/template/.hermes/skills/yss-web-controller/assets/templates/web/dto/UpdateRequest.java.template

@@ -1,19 +0,0 @@
-package ${base_package}.rest.dto.request;
-
-import ${command_dto_type};
-import lombok.Getter;
-import lombok.Setter;
-import ${validation_namespace}.validation.constraints.NotBlank;
-import ${validation_namespace}.validation.constraints.NotNull;
-import java.util.Date;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-import java.time.LocalDate;
-
-/** ${domain_desc}更新请求。字段来自批准的 OpenAPI allowlist。 */
-@Getter
-@Setter
-public class ${domain_class}UpdateRequest extends ${command_dto_simple_name} {
-
-${field_declarations}
-}

package/template/.hermes/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -1,86 +0,0 @@
-# YSS Web Adapter Target Profile 指南
-
-Web Adapter 负责 HTTP 边界、Wire DTO、校验、YSS Result 包装、WebConvertor 和异常翻译。它只调用 Application，不直接访问 Domain Gateway、Repository 或 PO。
-
-## 1. 包结构
-
-```text
-{base_package}.rest
-├── dto
-│   ├── request
-│   └── response
-├── convertor
-├── exception
-└── *Controller.java
-```
-
-DTO 固定属于 Web module。独立 client module 与把 client DTO 放进 Domain module 均为 `unsupported`；如未来确需发布复用制品，必须另行设计并批准新的 Target Profile，不能由当前脚手架推断或回退。
-
-## 2. Wire 合同
-
-- Request/Response 字段必须来自冻结 OpenAPI 和批准 allowlist。
-- 数据库 metadata 只补充 Java 类型候选，不能自行扩大公开字段。
-- Web Page Request 不继承含内部协作字段的 `PageQuery`；分页字段、默认值、枚举和禁用字段全部来自合同绑定且 digest 匹配的 `yss-dto` wire profile，再与 `fields.<table>.pagination` allowlist 取交集。Web Adapter 不维护第二份分页协议。
-- `orderBy` / `groupBy` 必须在 Application/Infrastructure 映射到数据库列白名单。
-- `offset`、`needTotalCount`、`tempTotalCount` 禁止进入 HTTP 绑定面。
-
-## 3. Controller
-
-```java
-@RestController
-@RequestMapping("/api/quality/quality-rule")
-@RequiredArgsConstructor
-@Tag(name = "质量规则管理")
-public class QualityRuleController {
-    private final QualityRuleService service;
-    private final QualityRuleWebConvertor webConvertor;
-
-    @PostMapping
-    public SingleResult<Long> create(@Valid @RequestBody QualityRuleCreateRequest request) {
-        return SingleResult.of(service.create(webConvertor.toCreateCommand(request)));
-    }
-}
-```
-
-- 只使用 OpenAPI 3 `io.swagger.v3.oas.annotations`；Swagger 2 为 `unsupported`，不存在 legacy Profile。
-- Controller 不捕获通用 `Exception`，不写业务规则，不手工执行持久化分页。
-- Controller seam 只出现 Web Request/Response 和 Application Service。
-
-## 4. WebConvertor
-
-```java
-@Mapper(componentModel = "spring")
-public interface QualityRuleWebConvertor {
-    QualityRuleCreateCommand toCreateCommand(QualityRuleCreateRequest source);
-    QualityRuleResponse toResponse(QualityRuleResult source);
-}
-```
-
-- 使用构造器注入，不定义静态 `INSTANCE`。
-- Request → Application Command/Query；Application Result → Response。
-- 不导入 Domain Model 或 Repository PO。
-- 父 POM 必须配置 MapStruct processor、Lombok 与 `lombok-mapstruct-binding`，验证生成实现真实编译。
-
-## 5. Exception Translator
-
-- Domain/Application 错误经专门 Translator 映射为冻结 API 的 HTTP status、YSS error code 和消毒后的公开消息。
-- known business、known system、unknown/runtime 三类都必须有 MockMvc/HTTP contract test。
-- unknown/runtime 保留内部 cause/stack 用于日志，但公开响应禁止返回 `getLocalizedMessage()`。
-- 复用 YSS global handler 前必须实测 auto-configuration 和 precedence；未经验证不能仅凭依赖存在宣称生效。
-
-## 6. 生成门禁
-
-- `generate_controller.mjs` 只消费 `schema_version=2`、`status=approved` 且 `current_version=contract_version` 的 Web generation contract；schema v1 为 `unsupported`。
-- `references/web-generation-contract.schema.json` 是 Web generation contract v2 的机器可读结构合同；生成器仍执行跨字段、文件系统与 Manifest 语义校验。
-- 合同必须声明 Slice `contract_id/contract_version/slice_id`、`integration_mode`、`implementation_project_root`、`allowed_write_paths`、预期证据、验证命令、`base_package`、`module_name`、`domain_segment`、Application Service package、`target-domain-model`、平台/validation Profile、`dto_placement=web`、`dto_wire_profile_ref/digest`、OpenAPI Freeze 引用和每张表的 create/update/query/pagination/response allowlist；CLI 身份必须逐项匹配。
-- `scaffold-v2` 模式必须绑定已达 `empty-scaffold-verified` 或 `first-slice-verified` 的 Manifest，并校验标准 Web module 路径和所有 Profile；`existing-project` 模式不得伪造 scaffold manifest。
-- 生成器是 initialize-only，必须在写入前规划全部目标并校验每个目标位于批准写路径；任一文件已存在或传入 `--force` 时整体阻断。落盘使用排他创建，任一步失败都回滚本次已创建文件，不允许部分成功。
-- 权限、校验语义、异常行为和复杂查询仍使用 `behavior-tdd`，不能由 metadata 猜测。
-
-## 7. 验证
-
-- Controller 只依赖 Application。
-- WebConvertor 无 Domain/Infrastructure import，并由 Spring 注入。
-- Wire forbidden fields 无法绑定。
-- OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
-- 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。

package/template/.hermes/skills/yss-web-controller/references/web-generation-contract.schema.json

@@ -1,97 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://yss.local/schemas/web-generation-contract.schema.json",
-  "title": "YSS Web Generation Contract",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schema_version",
-    "contract_id",
-    "contract_version",
-    "current_version",
-    "slice_id",
-    "status",
-    "integration_mode",
-    "implementation_project_root",
-    "base_package",
-    "module_name",
-    "domain_segment",
-    "application_service_package",
-    "architecture_profile",
-    "platform_profile",
-    "validation_namespace",
-    "dto_placement",
-    "dto_wire_profile_ref",
-    "dto_wire_profile_digest",
-    "openapi_freeze_ref",
-    "allowed_write_paths",
-    "expected_evidence_files",
-    "verification_commands",
-    "fields"
-  ],
-  "properties": {
-    "schema_version": { "const": 2 },
-    "contract_id": { "$ref": "#/$defs/nonEmptyString" },
-    "contract_version": { "type": "integer", "minimum": 1 },
-    "current_version": { "type": "integer", "minimum": 1 },
-    "slice_id": { "$ref": "#/$defs/nonEmptyString" },
-    "status": { "const": "approved" },
-    "integration_mode": { "enum": ["existing-project", "scaffold-v2"] },
-    "implementation_project_root": { "$ref": "#/$defs/nonEmptyString" },
-    "scaffold_manifest_ref": { "$ref": "#/$defs/nonEmptyString" },
-    "base_package": { "$ref": "#/$defs/nonEmptyString" },
-    "module_name": { "$ref": "#/$defs/nonEmptyString" },
-    "domain_segment": { "$ref": "#/$defs/nonEmptyString" },
-    "application_service_package": { "$ref": "#/$defs/nonEmptyString" },
-    "architecture_profile": { "const": "target-domain-model" },
-    "platform_profile": { "enum": ["spring-boot-2.7-jdk8", "spring-boot-3-jdk17"] },
-    "validation_namespace": { "enum": ["javax", "jakarta"] },
-    "dto_placement": { "const": "web" },
-    "dto_wire_profile_ref": { "$ref": "#/$defs/nonEmptyString" },
-    "dto_wire_profile_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-    "openapi_freeze_ref": { "$ref": "#/$defs/nonEmptyString" },
-    "allowed_write_paths": { "$ref": "#/$defs/nonEmptyStringArray" },
-    "expected_evidence_files": { "$ref": "#/$defs/nonEmptyStringArray" },
-    "verification_commands": { "$ref": "#/$defs/nonEmptyStringArray" },
-    "fields": {
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["create", "update", "query", "pagination", "response"],
-        "properties": {
-          "create": { "$ref": "#/$defs/stringArray" },
-          "update": { "$ref": "#/$defs/stringArray" },
-          "query": { "$ref": "#/$defs/stringArray" },
-          "pagination": {
-            "type": "array",
-            "uniqueItems": true,
-            "items": { "$ref": "#/$defs/nonEmptyString" }
-          },
-          "response": { "$ref": "#/$defs/stringArray" }
-        }
-      }
-    }
-  },
-  "allOf": [
-    {
-      "if": { "properties": { "integration_mode": { "const": "scaffold-v2" } } },
-      "then": { "required": ["scaffold_manifest_ref"] },
-      "else": { "not": { "required": ["scaffold_manifest_ref"] } }
-    },
-    {
-      "if": { "properties": { "platform_profile": { "const": "spring-boot-2.7-jdk8" } } },
-      "then": { "properties": { "validation_namespace": { "const": "javax" } } }
-    },
-    {
-      "if": { "properties": { "platform_profile": { "const": "spring-boot-3-jdk17" } } },
-      "then": { "properties": { "validation_namespace": { "const": "jakarta" } } }
-    }
-  ],
-  "$defs": {
-    "nonEmptyString": { "type": "string", "minLength": 1 },
-    "stringArray": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/nonEmptyString" } },
-    "nonEmptyStringArray": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/nonEmptyString" } }
-  }
-}

package/template/.hermes/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -1,226 +0,0 @@
-#!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { constants, access, copyFile, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
-
-const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
-const PLATFORM_VALIDATION_NAMESPACES = {
-  "spring-boot-2.7-jdk8": "javax",
-  "spring-boot-3-jdk17": "jakarta"
-};
-const required = ["metadata-file", "contract-file", "dto-wire-profile-file", "base-package", "module-name", "domain-segment"];
-const valued = new Set([...required, "output-dir", "web-project-dir", "web-output-dir", "author", "application-service-package", "validation-namespace", "scaffold-manifest-file"]);
-
-function usage() {
-  return "Usage: node generate_controller.mjs --metadata-file FILE --contract-file FILE --dto-wire-profile-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--web-project-dir DIR] [--web-output-dir DIR] [--scaffold-manifest-file FILE] [--author NAME] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
-}
-export function parseArgs(argv) {
-  const args = { "output-dir": "./output", author: "System", "validation-namespace": "javax", force: false };
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--help" || token === "-h") return { help: true };
-    if (token === "--force") throw new Error("unsupported: initialize-only Web 生成禁止 --force、已有目标覆盖和旧项目迁移");
-    if (!token.startsWith("--") || !valued.has(token.slice(2))) throw new Error(`unrecognized argument: ${token}`);
-    const value = argv[++index];
-    if (!value || value.startsWith("--")) throw new Error(`argument ${token} requires a value`);
-    args[token.slice(2)] = value;
-  }
-  for (const key of required) if (!args[key]) throw new Error(`the following arguments are required: --${key}`);
-  if (!new Set(["javax", "jakarta"]).has(args["validation-namespace"])) throw new Error("--validation-namespace must be javax or jakarta");
-  return args;
-}
-const pascal = (value) => value.toLowerCase().split("_").map((part) => part ? part[0].toUpperCase() + part.slice(1) : "").join("");
-const lowerCamel = (value) => { const output = pascal(value); return output ? output[0].toLowerCase() + output.slice(1) : ""; };
-const kebab = (value) => value.toLowerCase().replaceAll("_", "-");
-const packagePath = (value) => value.replaceAll(".", path.sep);
-const ensureSubdir = (root, name) => path.basename(path.normalize(root)) === name ? root : path.join(root, name);
-const javaType = (sqlType = "") => TYPE_MAPPING[sqlType.toLowerCase().split("(")[0]] || "String";
-
-function fields(columns, selected, { command = false } = {}) {
-  const byName = new Map(columns.map((column) => [String(column.name), column]));
-  return selected.map((field) => {
-    const column = byName.get(field);
-    if (!column) throw new Error(`approved field is absent from metadata: ${field}`);
-    const type = javaType(column.sql_type);
-    const name = lowerCamel(column.name);
-    const comment = column.comment || "";
-    const documentation = comment ? `    /**\n     * ${comment}\n     */\n` : "";
-    const validation = command && !column.nullable ? `    @${type === "String" ? "NotBlank" : "NotNull"}(message = \"${comment || name}不能为空\")\n` : "";
-    return `${documentation}${validation}    private ${type} ${name};`;
-  }).join("\n\n");
-}
-function render(template, context) { return template.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, plain) => { const key = braced || plain; if (!(key in context)) throw new Error(`missing template field: ${key}`); return context[key]; }); }
-async function exists(target) { try { await access(target); return true; } catch { return false; } }
-const present = (value) => value !== undefined && value !== null && value !== "";
-function within(root, target) {
-  const relative = path.relative(path.resolve(root), path.resolve(target));
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-function simpleJavaName(javaType) {
-  return javaType.replace(/<.*$/, "").split(".").at(-1);
-}
-function paginationFields(selected, dtoProfile) {
-  const definitions = dtoProfile.page_query.fields;
-  const unique = [...new Set(selected)];
-  const unsupported = unique.filter((name) => !(name in definitions) || dtoProfile.page_query.forbidden_client_fields.includes(name));
-  if (unsupported.length) throw new Error(`unsupported pagination fields: ${unsupported.join(", ")}`);
-  return unique.map((name) => {
-    const definition = definitions[name];
-    const wireType = definition.wire_types.find((item) => item !== "null");
-    const javaType = wireType === "integer" ? (definition.nullable ? "Integer" : "int") : wireType === "string" ? "String" : null;
-    if (!javaType) throw new Error(`unsupported yss-dto pagination wire type for ${name}: ${definition.wire_types.join(", ")}`);
-    const annotation = definition.enum?.length
-      ? `    @Pattern(regexp = "${definition.enum.join("|")}", message = "${name} must be one of ${definition.enum.join(", ")}")\n`
-      : "";
-    const initializer = definition.default === undefined ? "" : ` = ${typeof definition.default === "string" ? JSON.stringify(definition.default) : definition.default}`;
-    return `${annotation}    private ${javaType} ${name}${initializer};`;
-  }).join("\n");
-}
-
-async function loadDtoWireProfile(contract, args) {
-  const profilePath = path.resolve(args["dto-wire-profile-file"]);
-  if (profilePath !== path.resolve(contract.dto_wire_profile_ref ?? "")) throw new Error("--dto-wire-profile-file does not match the approved Web generation contract");
-  if (!await exists(profilePath)) throw new Error(`yss-dto wire profile not found: ${profilePath}`);
-  const source = await readFile(profilePath);
-  const digest = createHash("sha256").update(source).digest("hex");
-  if (digest !== contract.dto_wire_profile_digest) throw new Error("yss-dto wire profile digest does not match the approved Web generation contract");
-  const document = parseDocument(source.toString("utf8"), { maxAliasCount: 0, uniqueKeys: true });
-  if (document.errors.length) throw new Error(`invalid yss-dto wire profile: ${document.errors[0].message}`);
-  const profile = document.toJS({ maxAliasCount: 0 });
-  if (profile?.schema_version !== 1 || profile?.kind !== "yss-dto-openapi-wire-profile") throw new Error("unsupported yss-dto wire profile");
-  const resultPackage = profile.canonical?.java_package;
-  const pageResult = profile.wrappers?.PageResult;
-  const singleResult = profile.wrappers?.SingleResult;
-  const commandDtoType = profile.request_bases?.command?.java_type;
-  const queryDtoType = profile.request_bases?.query?.java_type;
-  if (![resultPackage, pageResult?.java_type, singleResult?.java_type, commandDtoType, queryDtoType].every(present)) throw new Error("incomplete yss-dto wire profile type mapping");
-  if (![pageResult.java_type, singleResult.java_type].every((type) => type.startsWith(`${resultPackage}.`))) throw new Error("yss-dto result wrapper package is inconsistent");
-  if (!profile.page_query?.fields || !Array.isArray(profile.page_query?.forbidden_client_fields)) throw new Error("incomplete yss-dto page_query mapping");
-  const factory = pageResult.java_factory;
-  const singleFactory = singleResult.java_factory;
-  const javaIdentifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-  if (!javaIdentifier.test(factory?.method ?? "") || !Array.isArray(factory.arguments) || !factory.arguments.length) throw new Error("incomplete yss-dto PageResult factory mapping");
-  if (!javaIdentifier.test(singleFactory?.method ?? "") || JSON.stringify(singleFactory.arguments) !== JSON.stringify(["data"])) throw new Error("incomplete yss-dto SingleResult factory mapping");
-  const expressionByArgument = { data: "toResponses(source.getData())", totalCount: "source.getTotalCount()", pageSize: "source.getPageSize()", pageIndex: "source.getPageIndex()" };
-  const unsupportedArguments = factory.arguments.filter((name) => !(name in expressionByArgument));
-  if (unsupportedArguments.length) throw new Error(`unsupported yss-dto PageResult factory arguments: ${unsupportedArguments.join(", ")}`);
-  return {
-    profile,
-    resultPackage,
-    pageResultType: pageResult.java_type.replace(/<.*$/, ""),
-    singleResultType: singleResult.java_type.replace(/<.*$/, ""),
-    pageResultFactoryMethod: factory.method,
-    singleResultFactoryMethod: singleFactory.method,
-    commandDtoType,
-    queryDtoType,
-    pageResultFactoryArguments: factory.arguments.map((name, index) => `                ${expressionByArgument[name]}${index < factory.arguments.length - 1 ? "," : ""}`).join("\n")
-  };
-}
-
-async function validateContract(contract, args) {
-  if (contract.schema_version !== 2) throw new Error(`web generation contract schema_version=${contract.schema_version} is unsupported; only schema_version=2 is accepted`);
-  if (contract.status !== "approved") throw new Error("web generation contract must be approved");
-  const requiredFields = ["contract_id", "contract_version", "current_version", "slice_id", "integration_mode", "implementation_project_root", "base_package", "module_name", "domain_segment", "application_service_package", "architecture_profile", "platform_profile", "validation_namespace", "dto_placement", "dto_wire_profile_ref", "dto_wire_profile_digest", "openapi_freeze_ref", "fields", "allowed_write_paths", "expected_evidence_files", "verification_commands"];
-  const missing = requiredFields.filter((name) => !present(contract[name]));
-  if (missing.length) throw new Error(`approved web generation contract is incomplete: ${missing.join(", ")}`);
-  if (contract.current_version !== contract.contract_version) throw new Error("web generation contract is not the current approved version");
-  if (!Number.isInteger(contract.contract_version) || contract.contract_version < 1) throw new Error("web generation contract_version must be a positive integer");
-  if (!["existing-project", "scaffold-v2"].includes(contract.integration_mode)) throw new Error("unsupported web generation integration_mode");
-  if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((name) => Array.isArray(contract[name]) && contract[name].length)) throw new Error("web generation contract requires non-empty allowed_write_paths, expected_evidence_files, and verification_commands");
-  if (contract.architecture_profile !== "target-domain-model" || contract.dto_placement !== "web") throw new Error("web generation only supports target-domain-model with dto_placement=web");
-  if (contract.base_package !== args["base-package"] || contract.module_name !== args["module-name"] || contract.domain_segment !== args["domain-segment"]) throw new Error("CLI generation identity does not match the approved web generation contract");
-  const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
-  if (contract.application_service_package !== applicationPackage) throw new Error("--application-service-package does not match the approved web generation contract");
-  if (!(contract.platform_profile in PLATFORM_VALIDATION_NAMESPACES)) throw new Error("unsupported platform_profile in approved web generation contract");
-  if (PLATFORM_VALIDATION_NAMESPACES[contract.platform_profile] !== contract.validation_namespace) throw new Error("platform_profile and validation_namespace are inconsistent");
-  if (contract.validation_namespace !== args["validation-namespace"]) throw new Error("--validation-namespace must match the approved web generation contract");
-
-  const implementationRoot = path.resolve(contract.implementation_project_root);
-  if (contract.integration_mode === "existing-project") {
-    if (args["scaffold-manifest-file"] || present(contract.scaffold_manifest_ref)) throw new Error("existing-project Web generation must not claim a scaffold manifest");
-    return { applicationPackage, implementationRoot };
-  }
-
-  if (!args["scaffold-manifest-file"] || !present(contract.scaffold_manifest_ref)) throw new Error("scaffold-v2 Web generation requires --scaffold-manifest-file and scaffold_manifest_ref");
-  const manifestPath = path.resolve(args["scaffold-manifest-file"]);
-  if (manifestPath !== path.resolve(contract.scaffold_manifest_ref)) throw new Error("--scaffold-manifest-file does not match the approved web generation contract");
-  if (!await exists(manifestPath)) throw new Error(`scaffold manifest not found: ${manifestPath}`);
-  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-  if (manifest.schema_version !== 2) throw new Error("scaffold manifest must use schema_version=2");
-  if (!["empty-scaffold-verified", "first-slice-verified"].includes(manifest.completion_level)) throw new Error("scaffold manifest must be empty-scaffold-verified before Web generation");
-  const scaffoldRoot = path.dirname(path.dirname(manifestPath));
-  if (implementationRoot !== scaffoldRoot) throw new Error("implementation_project_root does not match the scaffold manifest project root");
-  const expectedWebProject = path.join(scaffoldRoot, `${manifest.project_name}-adapter`, `${manifest.project_name}-web`);
-  if (!args["web-project-dir"] || path.resolve(args["web-project-dir"]) !== expectedWebProject) throw new Error("--web-project-dir does not match the scaffold manifest project layout");
-  const profilePairs = [["architecture", "architecture_profile"], ["platform", "platform_profile"], ["validation_namespace", "validation_namespace"], ["dto_placement", "dto_placement"]];
-  for (const [manifestField, contractField] of profilePairs) {
-    if (manifest.profiles?.[manifestField] !== contract[contractField]) throw new Error(`scaffold manifest ${manifestField} profile does not match the approved Web contract`);
-  }
-  if (manifest.base_package !== contract.base_package) throw new Error("scaffold manifest base_package does not match the approved Web contract");
-  return { applicationPackage, implementationRoot };
-}
-
-export async function generate(args, logger = console) {
-  if (!await exists(args["metadata-file"])) throw new Error(`Metadata file not found: ${args["metadata-file"]}`);
-  if (!await exists(args["contract-file"])) throw new Error(`Contract file not found: ${args["contract-file"]}`);
-  let metadata;
-  try { metadata = JSON.parse(await readFile(args["metadata-file"], "utf8")); } catch (error) { throw new Error(`Error reading metadata file: ${error.message}`); }
-  let contract;
-  try { contract = JSON.parse(await readFile(args["contract-file"], "utf8")); } catch (error) { throw new Error(`Error reading contract file: ${error.message}`); }
-  const { applicationPackage, implementationRoot } = await validateContract(contract, args);
-  const dto = await loadDtoWireProfile(contract, args);
-  const tables = metadata.tables || [];
-  if (!tables.length) { logger.warn("Warning: No tables found in metadata."); return []; }
-  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-  const templatesDir = path.resolve(scriptDir, "../assets/templates");
-  const template = async (name) => { const target = path.join(templatesDir, name); if (!await exists(target)) throw new Error(`Template not found: ${target}`); return readFile(target, "utf8"); };
-  const templateNames = ["Controller.java.template", "WebConvertor.java.template", "web/dto/Response.java.template", "web/dto/CreateRequest.java.template", "web/dto/UpdateRequest.java.template", "web/dto/PageRequest.java.template"];
-  const templates = Object.fromEntries(await Promise.all(templateNames.map(async (name) => [name, await template(name)])));
-  const basePath = packagePath(args["base-package"]);
-  const webBase = args["web-output-dir"] || (args["web-project-dir"] ? path.join(args["web-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
-  const webRoot = ensureSubdir(webBase, "rest");
-  const planned = [];
-  const plan = (target, contents) => planned.push({ target, contents });
-  for (const table of tables) {
-    const domainClass = pascal(table.table_name); const domainVar = lowerCamel(table.table_name); const domainDesc = String(table.table_comment || domainClass).trim().replaceAll("\n", " ");
-    const approvedFields = contract.fields[table.table_name];
-    if (!approvedFields || ["create", "update", "query", "pagination", "response"].some((name) => !Array.isArray(approvedFields[name]))) throw new Error(`approved web field contract is missing create/update/query/pagination/response allowlists for table: ${table.table_name}`);
-    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.rest.dto.request.${domainClass}CreateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}UpdateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}PageRequest;`, `import ${args["base-package"]}.rest.dto.response.${domainClass}Response;`].join("\n"), application_type_imports: [`import ${args["base-package"]}.application.command.${domainClass}CreateCommand;`, `import ${args["base-package"]}.application.command.${domainClass}UpdateCommand;`, `import ${args["base-package"]}.application.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.application.result.${domainClass}Result;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(webConvertor.toPageQuery(request))`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(webConvertor.toCreateCommand(request))`, update_call: `${domainVar}Service.update(webConvertor.toUpdateCommand(request))`, delete_call: `${domainVar}Service.delete(id)`, response_class: `${domainClass}Response`, create_request_class: `${domainClass}CreateRequest`, update_request_class: `${domainClass}UpdateRequest`, page_request_class: `${domainClass}PageRequest`, validation_namespace: args["validation-namespace"], result_package: dto.resultPackage, page_result_type: dto.pageResultType, page_result_simple_name: simpleJavaName(dto.pageResultType), page_result_factory_method: dto.pageResultFactoryMethod, single_result_type: dto.singleResultType, single_result_simple_name: simpleJavaName(dto.singleResultType), single_result_factory_method: dto.singleResultFactoryMethod, command_dto_type: dto.commandDtoType, command_dto_simple_name: simpleJavaName(dto.commandDtoType), query_dto_type: dto.queryDtoType, query_dto_simple_name: simpleJavaName(dto.queryDtoType), page_result_factory_arguments: dto.pageResultFactoryArguments };
-    plan(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
-    plan(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
-    for (const [templateName, target, declaration] of [["web/dto/Response.java.template", path.join(webRoot, "dto", "response", `${domainClass}Response.java`), fields(table.columns || [], approvedFields.response)], ["web/dto/CreateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}CreateRequest.java`), fields(table.columns || [], approvedFields.create, { command: true })], ["web/dto/UpdateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}UpdateRequest.java`), fields(table.columns || [], approvedFields.update, { command: true })], ["web/dto/PageRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}PageRequest.java`), fields(table.columns || [], approvedFields.query)]]) plan(target, render(templates[templateName], { ...context, field_declarations: declaration, pagination_field_declarations: paginationFields(approvedFields.pagination, dto.profile) }));
-  }
-  const targets = planned.map(({ target }) => target);
-  if (new Set(targets).size !== targets.length) throw new Error("approved metadata produces duplicate target files");
-  const existing = [];
-  for (const target of targets) if (await exists(target)) existing.push(target);
-  if (existing.length) throw new Error(`initialize-only Web generation refuses existing targets: ${existing.join(", ")}`);
-  const allowedRoots = contract.allowed_write_paths.map((item) => path.resolve(implementationRoot, String(item)));
-  const outside = targets.filter((target) => !allowedRoots.some((root) => within(root, target)));
-  if (outside.length) throw new Error(`planned Web targets are outside allowed_write_paths: ${outside.join(", ")}`);
-  const staging = await mkdtemp(path.join(tmpdir(), "yss-web-generation-"));
-  const created = [];
-  try {
-    for (const [index, { contents }] of planned.entries()) await writeFile(path.join(staging, String(index)), contents, "utf8");
-    for (const [index, { target }] of planned.entries()) {
-      await mkdir(path.dirname(target), { recursive: true });
-      await copyFile(path.join(staging, String(index)), target, constants.COPYFILE_EXCL);
-      created.push(target);
-      logger.log(`Generated: ${target}`);
-    }
-  } catch (error) {
-    for (const target of created.reverse()) {
-      try { await unlink(target); } catch (cleanupError) { if (cleanupError.code !== "ENOENT") error.cleanupError = cleanupError.message; }
-    }
-    throw error;
-  } finally {
-    await rm(staging, { recursive: true, force: true });
-  }
-  return targets;
-}
-async function main() { try { const args = parseArgs(process.argv.slice(2)); if (args.help) { console.log(usage()); return; } await generate(args); } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; } }
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main();