create-yss-spec 2.2.9 → 3.0.0

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

@@ -1,21 +1,29 @@
 #!/usr/bin/env node
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+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 required = ["metadata-file", "base-package", "module-name", "domain-segment"];
-const valued = new Set([...required, "output-dir", "domain-project-dir", "web-project-dir", "domain-output-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
+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 --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--domain-project-dir DIR] [--web-project-dir DIR] [--domain-output-dir DIR] [--web-output-dir DIR] [--author NAME] [--force] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
+  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") { args.force = true; continue; }
+    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`);
@@ -32,9 +40,11 @@ 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, { skipPk = false, command = false, skipAudit = true } = {}) {
-  const audit = new Set(["create_time", "update_time", "create_by", "update_by", "deleted", "version"]);
-  return columns.filter((column) => !(skipPk && column.primary) && !(skipAudit && audit.has(String(column.name).toLowerCase()))).map((column) => {
+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 || "";
@@ -45,33 +55,172 @@ function fields(columns, { skipPk = false, command = false, skipAudit = true } =
 }
 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 templates = Object.fromEntries(await Promise.all(["Controller.java.template", "WebConvertor.java.template", "domain/vo/VO.java.template", "domain/dto/cmd/AddCmd.java.template", "domain/dto/cmd/UpdateCmd.java.template", "domain/dto/query/PageQuery.java.template"].map(async (name) => [name, await template(name)])));
+  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 domainBase = args["domain-output-dir"] || (args["domain-project-dir"] ? path.join(args["domain-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
   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 domainRoot = ensureSubdir(domainBase, "client");
   const webRoot = ensureSubdir(webBase, "rest");
-  const written = [];
-  const write = async (target, contents) => { await mkdir(path.dirname(target), { recursive: true }); if (!await exists(target) || args.force) { await writeFile(target, contents, "utf8"); logger.log(`Generated: ${target}`); written.push(target); } else logger.log(`Skipped (exists): ${target}`); };
+  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 applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
-    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"]}.client.dto.cmd.${domainClass}AddCmd;`, `import ${args["base-package"]}.client.dto.cmd.${domainClass}UpdateCmd;`, `import ${args["base-package"]}.client.dto.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.client.vo.${domainClass}VO;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, domain_import: `import ${args["base-package"]}.domain.${args["domain-segment"]}.model.${domainClass};`, 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(query)`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(cmd)`, update_call: `${domainVar}Service.update(cmd)`, delete_call: `${domainVar}Service.delete(id)`, vo_class: `${domainClass}VO`, add_cmd_class: `${domainClass}AddCmd`, update_cmd_class: `${domainClass}UpdateCmd`, query_class: `${domainClass}PageQuery`, validation_namespace: args["validation-namespace"] };
-    await write(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
-    await write(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
-    for (const [templateName, target, declaration] of [["domain/vo/VO.java.template", path.join(domainRoot, "vo", `${domainClass}VO.java`), fields(table.columns || [], { skipAudit: false })], ["domain/dto/cmd/AddCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}AddCmd.java`), fields(table.columns || [], { skipPk: true, command: true })], ["domain/dto/cmd/UpdateCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}UpdateCmd.java`), fields(table.columns || [], { command: true })], ["domain/dto/query/PageQuery.java.template", path.join(domainRoot, "dto/query", `${domainClass}PageQuery.java`), fields(table.columns || [])]]) await write(target, render(templates[templateName], { ...context, field_declarations: declaration }));
+    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 written;
+  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();

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

@@ -1,19 +1,156 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import { generate, parseArgs } from "./generate_controller.mjs";
 
-test("generates application-service controller with requested validation profile", async () => {
+const scripts = path.dirname(fileURLToPath(import.meta.url));
+const dtoWireProfileFile = path.resolve(scripts, "../../yss-dto/references/openapi-wire-profile.yaml");
+const dtoWireProfileDigest = createHash("sha256").update(await readFile(dtoWireProfileFile)).digest("hex");
+
+const metadataValue = {
+  tables: [{
+    table_name: "quality_rule",
+    table_comment: "质量规则",
+    columns: [
+      { name: "id", sql_type: "bigint", primary: true, nullable: false },
+      { name: "rule_name", sql_type: "varchar(64)", nullable: false }
+    ]
+  }]
+};
+
+function webContract(root, overrides = {}) {
+  return {
+    schema_version: 2,
+    contract_id: "slice-quality-web-1",
+    contract_version: 1,
+    current_version: 1,
+    slice_id: "quality-rule-create",
+    status: "approved",
+    integration_mode: "existing-project",
+    implementation_project_root: root,
+    base_package: "com.yss.demo",
+    module_name: "demo",
+    domain_segment: "quality",
+    application_service_package: "com.yss.demo.application.service",
+    architecture_profile: "target-domain-model",
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    dto_placement: "web",
+    dto_wire_profile_ref: dtoWireProfileFile,
+    dto_wire_profile_digest: dtoWireProfileDigest,
+    openapi_freeze_ref: "openapi://quality-rule@1",
+    allowed_write_paths: [root],
+    expected_evidence_files: ["evidence/web-generation.json"],
+    verification_commands: ["./mvnw test", "./mvnw package"],
+    fields: {
+      quality_rule: {
+        create: ["rule_name"],
+        update: ["id", "rule_name"],
+        query: ["rule_name"],
+        pagination: ["pageIndex", "pageSize"],
+        response: ["id", "rule_name"]
+      }
+    },
+    ...overrides
+  };
+}
+
+async function fixture(overrides = {}) {
   const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
   const metadata = path.join(root, "metadata.json");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", table_comment: "质量规则", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }, { name: "rule_name", sql_type: "varchar(64)", nullable: false }] }] }));
-  await generate(parseArgs(["--metadata-file", metadata, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
-  const controller = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "QualityRuleController.java"), "utf8");
+  const contract = path.join(root, "web-contract.json");
+  const output = path.join(root, "out");
+  await writeFile(metadata, JSON.stringify(metadataValue));
+  await writeFile(contract, JSON.stringify(webContract(root, overrides)));
+  const args = ["--metadata-file", metadata, "--contract-file", contract, "--dto-wire-profile-file", dtoWireProfileFile, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", overrides.validation_namespace ?? "jakarta"];
+  return { root, metadata, contract, output, args };
+}
+
+test("generates approved standalone Web code and exposes only approved pagination fields", async () => {
+  const data = await fixture();
+  await generate(parseArgs(data.args), { log() {}, warn() {} });
+  const rest = path.join(data.output, "com", "yss", "demo", "rest");
+  const controller = await readFile(path.join(rest, "QualityRuleController.java"), "utf8");
+  const convertor = await readFile(path.join(rest, "convertor", "QualityRuleWebConvertor.java"), "utf8");
+  const createRequest = await readFile(path.join(rest, "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
+  const pageRequest = await readFile(path.join(rest, "dto", "request", "QualityRulePageRequest.java"), "utf8");
   assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
+  assert.match(controller, /SingleResult\.of\(/);
   assert.match(controller, /import jakarta\.validation\.Valid;/);
-  assert.doesNotMatch(controller, /Gateway/);
+  assert.match(convertor, /@Mapper\(componentModel = "spring"\)/);
+  assert.match(convertor, /PageResult\.of\(\s*toResponses\(source\.getData\(\)\),\s*source\.getTotalCount\(\),\s*source\.getPageSize\(\),\s*source\.getPageIndex\(\)/s);
+  assert.doesNotMatch(`${controller}\n${convertor}`, /Gateway|\.domain\.|Mappers\.getMapper|INSTANCE/);
+  assert.match(createRequest, /private String ruleName;/);
+  assert.doesNotMatch(createRequest, /private Long id;|@Data/);
+  assert.match(pageRequest, /private int pageIndex = 1;/);
+  assert.match(pageRequest, /private int pageSize = 10;/);
+  assert.doesNotMatch(pageRequest, /orderBy|orderDirection|groupBy|offset|needTotalCount|tempTotalCount|extends PageQuery/);
 });
 
-test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));
+test("rejects a yss-dto wire profile whose digest differs from the approved contract", async () => {
+  const data = await fixture({ dto_wire_profile_digest: "0".repeat(64) });
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /yss-dto wire profile digest/);
+});
+
+test("rejects missing CLI arguments, schema v1, draft contracts, and inconsistent platform profiles", async () => {
+  assert.throws(() => parseArgs(["--module-name", "demo"]), /required/);
+  const v1 = await fixture({ schema_version: 1 });
+  await assert.rejects(() => generate(parseArgs(v1.args), { log() {}, warn() {} }), /schema_version=1.*unsupported/);
+  const draft = await fixture({ status: "draft" });
+  await assert.rejects(() => generate(parseArgs(draft.args), { log() {}, warn() {} }), /approved/);
+  const mismatch = await fixture({ platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax" });
+  await assert.rejects(() => generate(parseArgs(mismatch.args), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
+  assert.throws(() => parseArgs([...draft.args, "--force"]), /initialize-only/);
+});
+
+test("binds identity and every target to the approved write scope before writing", async () => {
+  const data = await fixture();
+  await assert.rejects(() => generate(parseArgs(data.args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root, { allowed_write_paths: [path.join(data.root, "different-root")] })));
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /allowed_write_paths/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root)));
+  const existing = path.join(data.output, "com/yss/demo/rest/QualityRuleController.java");
+  await mkdir(path.dirname(existing), { recursive: true });
+  await writeFile(existing, "user-owned\n");
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /initialize-only/);
+  assert.equal(await readFile(existing, "utf8"), "user-owned\n");
+  await assert.rejects(() => readFile(path.join(data.output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+});
+
+test("scaffold-v2 mode requires an empty-scaffold-verified manifest with matching profile and project layout", async () => {
+  const data = await fixture({ platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax" });
+  const projectRoot = path.join(data.root, "demo-service");
+  const webProject = path.join(projectRoot, "demo-service-adapter", "demo-service-web");
+  const manifest = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  await mkdir(path.dirname(manifest), { recursive: true });
+  await writeFile(manifest, JSON.stringify({ schema_version: 2, project_name: "demo-service", base_package: "com.yss.demo", completion_level: "empty-scaffold-verified", profiles: { architecture: "target-domain-model", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web" } }));
+  const contractValue = webContract(projectRoot, {
+    integration_mode: "scaffold-v2",
+    implementation_project_root: projectRoot,
+    scaffold_manifest_ref: manifest,
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    allowed_write_paths: [path.join(webProject, "src/main/java/com/yss/demo/rest")]
+  });
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  const args = ["--metadata-file", data.metadata, "--contract-file", data.contract, "--dto-wire-profile-file", dtoWireProfileFile, "--scaffold-manifest-file", manifest, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--web-project-dir", webProject, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"];
+  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /scaffold manifest.*platform/i);
+  contractValue.platform_profile = "spring-boot-2.7-jdk8";
+  contractValue.validation_namespace = "javax";
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  await generate(parseArgs(args.map((value) => value === "jakarta" ? "javax" : value)), { log() {}, warn() {} });
+});
+
+test("rolls back files written before a filesystem failure", async () => {
+  const data = await fixture();
+  const rest = path.join(data.output, "com/yss/demo/rest");
+  await mkdir(rest, { recursive: true });
+  await writeFile(path.join(rest, "convertor"), "blocking-file\n");
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }));
+  await assert.rejects(() => readFile(path.join(rest, "QualityRuleController.java"), "utf8"), /ENOENT/);
+  assert.equal(await readFile(path.join(rest, "convertor"), "utf8"), "blocking-file\n");
+});

package/template/.codex/skills/ask-matt/SKILL.md

@@ -84,7 +84,7 @@ Off the main flow entirely.
 - **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
 - **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
-- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/yss-research`** — investigate technical or strategy evidence using `technical-evidence` / `strategy-evidence` and `quick` / `evidence-audited` modes. Use a background agent when the runtime supports it and parallel reading is useful; delegation is not a trust guarantee. The old `/research` name is a deprecated alias. Research feeds `/grill-with-docs` and lifecycle decisions; it does not approve them.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.

package/template/.codex/skills/code-review/references/yss-review-standards.md

@@ -12,10 +12,10 @@
 2. Slice Implementation Contract 的 `required_skills`：对每个技能读取 `.agents/skills/<id>/SKILL.md` 及该 skill 指明的 references。
 3. 影响面专项检查输入（与合同并集，不得互相替代）：
    - 后端：`alibaba-java-code-style`、`yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller`、`yss-dto`、`mapstruct`、`lombok`
-   - UI：`yss-ui`、`yss-design-system`、`yss-page-module-development`
+   - UI：`yss-ui`、`yss-design-system`、`yss-ui-business-page-generation`、`yss-page-module-development`
 4. 报告模板中的后端 / 前端门禁表。空着的适用行视为 `missing_evidence`。
 
-YSS 页面模块约定（YTable、YssFormily、页面骨架等）走 Standards，不并入 UI fidelity。UI fidelity 只核原型与状态矩阵。
+YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，不并入 UI fidelity。UI fidelity 只核原型与状态矩阵。
 
 审查者只读这些 skill，不得用它们写实现路径。`role.test-engineer` 任务包禁止 `implement` 与脚手架生成器。
 
@@ -51,4 +51,4 @@ YSS 页面模块约定（YTable、YssFormily、页面骨架等）走 Standards
 | `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；任何修复使候选失效，必须重新捕获并重跑 Standards、Spec、UI fidelity（若命中）和 fresh verification |
 | `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 Router 或更早生命周期阶段；禁止在旧合同上继续编码 |
 
-`not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
+`not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。

package/template/.codex/skills/component-selection-imports/SKILL.md

@@ -19,8 +19,8 @@ description: 指导 YSS UI 业务页面、CRUD、列表页、表单页和组件
 
 1. 当前会话可用 yss-ui MCP 时，先用 `list_components` 确认组件、Hook 或 Utils 是否真实存在，再用 `get_component_docs` 确认名称、导出包、Props、Events 和 Slots，不只看 demo 标签名。
 2. `get_component_docs` 未命中时，先用 `search_docs` 和 `list_components` 校正别名与归属，不得立即判定为未封装。
-3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文中的最新 `llms-full.txt`；上下文没有时读取 `http://192.168.164.27:3200/llms-full.txt`。
-4. 必要时读取 `../yss-page-module-development/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
+3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文或文档站的最新 `llms-full.txt`。
+4. 必要时读取 `../yss-ui-business-page-generation/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
 5. 已导出的 YSS 能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装后才从 `ant-design-vue` 导入原组件。
 6. 若文档与导出源码不一致，记录差异并按当前仓库可编译的导出处理，不猜测 API。
 

package/template/.codex/skills/frontend-commit/SKILL.md

@@ -14,7 +14,7 @@ description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微
 
 ## 不适用场景
 
-- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- yss-ui 组件库仓库自身的提交与发版：回到 yss-ui 源仓库使用其 `categories.library` 提交流程；该类 skill 不随业务模板分发。
 - Java、Spring Boot、Maven、Gradle 后端仓库：使用 `../java-backend-commit/SKILL.md`。
 - 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
 - 无代码改动，或改动内容与提交请求不匹配。

package/template/.codex/skills/product-design/package.json

@@ -1,11 +1,13 @@
 {
   "name": "product-design",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "private": true,
   "type": "module",
   "description": "The Product Design plugin is built for turning early ideas into prototypes teams can review. It starts design and build work by confirming the brief, then helps teams explore product directions, audit user flows, prototype from a live URL, and make static screenshots interactive.",
   "repository": "https://github.com/openai/role-specific-plugins/tree/main/plugins/product-design",
   "scripts": {
-    "prototype:bootstrap": "node scripts/bootstrap-prototype.mjs"
+    "prototype:bootstrap": "node scripts/bootstrap-prototype.mjs",
+    "research:test": "node skills/research/tests/run-scenarios.mjs",
+    "research:validate": "node skills/research/scripts/validate-research-package.mjs"
   }
 }

package/template/.codex/skills/product-design/skills/research/SKILL.md

@@ -9,6 +9,13 @@ Run a fresh UX research scan for the product the user specifies.
 
 Focus on current, evidence-backed user problems. Prioritize logged-in product experience, self-serve flows, onboarding, docs/help, developer experience, support friction, and product workflows.
 
+## Modes
+
+- `quick` is the default. It produces a sharp in-chat brief from the best available current evidence.
+- `evidence-audited` is opt-in. Use it only when the user explicitly asks for deep, strict, auditable, or `evidence-audited` research. For consequential product or investment decisions, recommend this mode but do not switch silently.
+
+Both modes remain UX research workflows. Do not import academic-paper writing, peer-review, publication, or multi-agent ceremony.
+
 ## Critical Overrides
 
 - Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
@@ -25,7 +32,9 @@ Do not inspect every saved reference. Inspect only what the current task needs.
 ## Contract
 
 - Restate the product, audience, time horizon, and research scope before scanning.
+- State the active mode. In `evidence-audited`, also state the planned source classes and inclusion/exclusion criteria before searching.
 - Use public sources by default. Use internal sources when the connectors are available and the user request allows it.
+- Search user-provided or saved material first, apply the same inclusion criteria to it, then search externally to fill material gaps. Never silently omit supplied material; report exclusions or access failures.
 - Cite sources wherever available.
 - Separate observed evidence from inference.
 - Do not overclaim from anecdotes.
@@ -70,6 +79,8 @@ Do not inspect every saved reference. Inspect only what the current task needs.
 
 7. Tell a clear product story.
 
+For `evidence-audited` mode, follow [evidence-audited.md](references/evidence-audited.md) after scope restatement. This adds a reproducible Search Log, an Evidence Ledger, key-claim audit, counter-signal handling, and an explicit failure policy. It does not require sentence-by-sentence auditing.
+
 ## Output
 
 Default to an in-chat research brief unless the user asks for another format.
@@ -81,6 +92,14 @@ Include:
 - Source map: what was searched, what each source contributed, and where signal was weak.
 - Opportunity map: group recommendations into fix this week, fix this quarter, and needs deeper research.
 
+When the user explicitly asks to persist an `evidence-audited` result, create two adjacent files named `<slug>-research-brief.md` and `<slug>-evidence.yaml`. Start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml), then run:
+
+```bash
+node scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
+```
+
+Run the command from this skill directory. Do not persist research files merely because `evidence-audited` mode is active.
+
 ## Rules
 
 - Use citations wherever available.
@@ -89,4 +108,7 @@ Include:
 - Separate UX friction from missing features.
 - Separate reliability/performance issues from UX workflow issues.
 - Mark internal-only evidence separately from public evidence.
+- Do not equate source count with frequency. State whether frequency is measured, repeated across independent sources, or anecdotal.
+- In `evidence-audited` mode, audit the key claims for every ranked problem: problem existence, impact, frequency characterization, and the evidence basis for the recommended move. Audit every high-severity key claim; for lower-severity problems include at least one primary supporting item and one counter-signal or an explicit `none-found` search result.
+- Unsupported key claims must use `needs-deeper-research`; partially supported claims must be qualified. Never label a persisted package audited when its validator has not passed.
 - Keep the brief sharp, specific, and easy to consume.