create-yss-spec 3.3.1 → 3.3.4

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -1,318 +0,0 @@
-#!/usr/bin/env node
-/** 依据生命周期批准的兼容 schema v3 或统一 schema v4 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
-import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
-import { createHash } from "node:crypto";
-import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
-import { findGitRoot, gitSubmoduleScaffoldViolation, overlayMountViolation } from "../../../../scripts/lib/repository-scope-policy.mjs";
-import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
-import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
-import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
-const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
-const SKILL_ID = "yss-layered-mvc-scaffold-generator";
-const COMMANDS = ["./mvnw validate", "./mvnw test", "./mvnw package"];
-const MODULE_ORDER = ["server", "service", "repository", "adapter", "client", "feign-client"];
-const CORE_MODULES = ["server", "service", "repository"];
-const CAPABILITIES = Object.freeze({
-  "external-integration": ["adapter"],
-  "published-client": ["client"],
-  "feign-client": ["client", "feign-client"]
-});
-
-function fail(message) { throw new Error(message); }
-function isPresent(value) { return value !== undefined && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0); }
-function sha256(content) { return `sha256:${createHash("sha256").update(content).digest("hex")}`; }
-function rawSha256(content) { return createHash("sha256").update(content).digest("hex"); }
-function isWithin(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
-function xml(value) { return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;"); }
-function toUpperCamel(value) { return value.split("-").map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join(""); }
-function orderedModules(requested) {
-  const modules = new Set(CORE_MODULES);
-  for (const capability of requested) {
-    if (!CAPABILITIES[capability]) fail(`unsupported MVC capability: ${capability}`);
-    for (const module of CAPABILITIES[capability]) modules.add(module);
-  }
-  return MODULE_ORDER.filter((module) => modules.has(module));
-}
-async function exists(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
-async function put(root, relative, content) { const target = path.join(root, relative); await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content.endsWith("\n") ? content : `${content}\n`, "utf8"); }
-async function fileEntries(root, excluded = new Set()) {
-  const entries = [];
-  async function visit(directory) {
-    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const target = path.join(directory, entry.name);
-      const relative = path.relative(root, target).split(path.sep).join("/");
-      if (entry.name === ".git") continue;
-      if (excluded.has(relative)) continue;
-      if (entry.isDirectory()) await visit(target);
-      else if (entry.isFile()) entries.push({ target, relative });
-    }
-  }
-  await visit(root);
-  return entries;
-}
-async function treeDigest(root) {
-  const hash = createHash("sha256");
-  async function visit(directory) {
-    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const target = path.join(directory, entry.name);
-      if (entry.isDirectory()) await visit(target);
-      else if (entry.isFile()) hash.update(path.relative(root, target)).update("\0").update(await readFile(target)).update("\0");
-    }
-  }
-  await visit(root);
-  return `sha256:${hash.digest("hex")}`;
-}
-
-export function parseArgs(argv) {
-  const options = { force: false };
-  const mapping = new Map([
-    ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
-    ["--contract-file", "contractFile"], ["--contract-id", "contractId"], ["--contract-version", "contractVersion"],
-    ["--approval-ref", "approvalRef"], ["--compiler-draft-ref", "compilerDraftRef"], ["--persisted-ref", "persistedRef"],
-    ["--group-id", "groupId"], ["--project-version", "projectVersion"], ["--parent-group-id", "parentGroupId"],
-    ["--parent-artifact-id", "parentArtifactId"], ["--parent-version", "parentVersion"], ["--yss-components-version", "yssComponentsVersion"]
-  ]);
-  for (let index = 0; index < argv.length; index += 1) {
-    let token = argv[index];
-    if (token === "--help" || token === "-h") { options.help = true; continue; }
-    if (token === "--force") { options.force = true; continue; }
-    const equal = token.indexOf("=");
-    let value;
-    if (equal >= 0) { value = token.slice(equal + 1); token = token.slice(0, equal); }
-    if (!mapping.has(token)) fail(`不支持的参数: ${token}`);
-    if (value === undefined) value = argv[++index];
-    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
-    options[mapping.get(token)] = value;
-  }
-  if (options.help) return options;
-  for (const key of mapping.values()) if (!isPresent(options[key])) fail(`缺少必填参数: ${key}`);
-  if (!/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("--project-name 必须是 kebab-case");
-  if (!/^[a-z](?:[a-z0-9]*)(?:\.[a-z](?:[a-z0-9]*)?)*$/.test(options.basePackage)) fail("--base-package 不是合法 Java 包名");
-  if (!/^\d+$/.test(options.contractVersion) || Number(options.contractVersion) < 1) fail("--contract-version 必须为正整数");
-  options.contractVersion = Number(options.contractVersion);
-  if (options.force) fail("unsupported: initialize-only 脚手架禁止 --force");
-  return options;
-}
-
-function dependency(groupId, artifactId, version = null, scope = null) {
-  return `<dependency><groupId>${xml(groupId)}</groupId><artifactId>${xml(artifactId)}</artifactId>${version ? `<version>${xml(version)}</version>` : ""}${scope ? `<scope>${scope}</scope>` : ""}</dependency>`;
-}
-
-function parentPom(contract, modules) {
-  const c = contract.maven_coordinates;
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
-  <modelVersion>4.0.0</modelVersion>
-  <parent><groupId>${xml(c.parent.group_id)}</groupId><artifactId>${xml(c.parent.artifact_id)}</artifactId><version>${xml(c.parent.version)}</version><relativePath/></parent>
-  <groupId>${xml(c.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(c.project_version)}</version><packaging>pom</packaging>
-  <properties><java.version>1.8</java.version><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>${xml(c.yss_components_version)}</yss-components.version></properties>
-  <modules>${modules.map((module) => `<module>${contract.project_name}-${module}</module>`).join("")}</modules>
-  <dependencyManagement><dependencies>${dependency("com.yss.cloud", "yss-components-bom", "${yss-components.version}", "import").replace("</dependency>", "<type>pom</type></dependency>")}</dependencies></dependencyManagement>
-  <build><pluginManagement><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><source>1.8</source><target>1.8</target><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.30</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
-</project>`;
-}
-
-function modulePom(contract, module, modules) {
-  const applicationModule = modules.includes("core") ? "core" : "service";
-  const own = (name) => dependency(contract.maven_coordinates.group_id, `${contract.project_name}-${name}`, "${project.version}");
-  const dependencies = [];
-  if (module === "server") {
-    dependencies.push(own(applicationModule), dependency("org.springframework.boot", "spring-boot-starter-web"), dependency("org.springframework.boot", "spring-boot-starter-validation"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.tngtech.archunit", "archunit-junit5", "1.2.1", "test"));
-    if (modules.includes("client")) dependencies.push(own("client"));
-    dependencies.push(dependency("com.h2database", "h2", null, "test"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("com.yss.cloud", "yss-component-dto"));
-  }
-  if (module === applicationModule) {
-    dependencies.push(own("repository"), dependency("org.springframework", "spring-tx"), dependency("com.yss.cloud", "yss-component-dto"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"));
-    if (modules.includes("adapter")) dependencies.push(own("adapter"));
-  }
-  if (module === "repository") {
-    dependencies.push(dependency("com.yss.cloud", "yss-component-mybatis-plus-starter"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.h2database", "h2", null, "test"));
-  }
-  if (module === "adapter") {
-    dependencies.push(dependency("org.springframework", "spring-context"));
-    if (modules.includes("feign-client")) dependencies.push(own("feign-client"));
-  }
-  if (module === "client") dependencies.push(dependency("com.yss.cloud", "yss-component-dto"), dependency("javax.validation", "validation-api"));
-  if (["server", "service", "core", "client", "repository"].includes(module)) dependencies.push(dependency("org.projectlombok", "lombok", "1.18.30", "provided"));
-  if (module === "feign-client") dependencies.push(own("client"), dependency("org.springframework.cloud", "spring-cloud-openfeign-core"));
-  const plugin = module === "server" ? `<profiles><profile><id>scaffold-local</id><dependencies>${dependency("com.h2database", "h2", null, "runtime")}</dependencies></profile></profiles><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>` : "";
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><parent><groupId>${xml(contract.maven_coordinates.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(contract.maven_coordinates.project_version)}</version></parent><artifactId>${xml(contract.project_name)}-${module}</artifactId><dependencies>${dependencies.join("")}</dependencies>${plugin}</project>`;
-}
-
-async function validateContract(options, skillId, architectureProfile) {
-  const contractFile = path.resolve(options.contractFile);
-  const contractText = await readFile(contractFile, "utf8").catch(() => fail(`脚手架合同不可读取: ${contractFile}`));
-  let contract;
-  try { contract = JSON.parse(contractText); } catch { fail("脚手架合同必须是 JSON 对象"); }
-  if (![3, 4].includes(contract.schema_version)) fail(`unsupported: 只接受兼容 scaffold contract v3 或统一 v4，收到 v${contract.schema_version}`);
-  if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-layered-mvc")) fail("schema v4 合同必须绑定 backend/backend-layered-mvc");
-  if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
-  const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
-  const missing = required.filter((field) => !isPresent(contract[field]));
-  if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
-  if (contract.status !== "approved" || (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true))) fail("脚手架合同必须已批准且为当前版本");
-  if (contract.contract_id !== options.contractId || contract.contract_version !== options.contractVersion || contract.compiler_draft_ref !== options.compilerDraftRef || contract.lifecycle_approval_ref !== options.approvalRef || contract.persisted_ref !== options.persistedRef) fail("命令行合同元数据与批准合同不一致");
-  if (contract.scaffold_status !== "required" || contract.architecture_family !== "layered-mvc" || contract.generator_skill !== skillId) fail("合同必须绑定 layered-mvc 与本生成器");
-  if (contract.project_name !== options.projectName || contract.base_package !== options.basePackage || path.resolve(contract.target_output_dir) !== path.resolve(options.outputDir)) fail("项目身份或输出目录与合同不一致");
-  if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((field) => Array.isArray(contract[field]) && contract[field].length)) fail("allowed_write_paths、expected_evidence_files、verification_commands 必须为非空数组");
-  const finalProjectRoot = path.join(path.resolve(options.outputDir), options.projectName);
-  const allowedRoots = contract.allowed_write_paths.map((item) => path.resolve(options.outputDir, String(item)));
-  if (!allowedRoots.some((root) => isWithin(root, finalProjectRoot))) fail("实际项目根不在合同 allowed_write_paths 内");
-  const expectedProfiles = { architecture: "layered-mvc", persistence: "mybatis-plus", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" };
-  for (const [field, value] of Object.entries(expectedProfiles)) if (contract.profiles?.[field] !== value) fail(`unsupported profile ${field}: ${contract.profiles?.[field]}`);
-  assertLocalDatabaseProfile(contract.profiles);
-  if (contract.architecture_profile !== architectureProfile) fail(`合同必须显式绑定 ${architectureProfile} Profile`);
-  const requested = contract.module_profile?.requested_capabilities;
-  if (!Array.isArray(requested)) fail("module_profile.requested_capabilities 必须是数组");
-  const resolved = architectureProfile === "mvc-data-analysis-v1" ? ["server", "core", "client", "repository", "adapter", "feign-client"] : orderedModules(requested);
-  if (contract.module_profile.resolution_version !== 1 || JSON.stringify(contract.module_profile.resolved_modules) !== JSON.stringify(resolved)) fail("MVC 能力闭包与 resolution_version=1 不一致");
-  if (JSON.stringify(contract.verification_commands) !== JSON.stringify(COMMANDS)) fail("验证命令必须固定为三条 ./mvnw 命令");
-  if (!contract.expected_evidence_files.includes(".yss/scaffold-generation.json")) fail("expected_evidence_files 必须包含 Manifest");
-  const work = contract.work_unit;
-  if (work?.primary_skill !== skillId || work?.tdd_mode !== "controlled-generation" || work?.controlled_generation !== true) fail("工作单元必须绑定本生成器和 controlled-generation");
-  if (!Array.isArray(work.allowed_write_paths) || !Array.isArray(work.expected_evidence) || !Array.isArray(work.verification_commands) || JSON.stringify(work.allowed_write_paths) !== JSON.stringify(contract.allowed_write_paths) || JSON.stringify(work.verification_commands) !== JSON.stringify(contract.verification_commands)) fail("工作单元与根级写路径或验证命令不一致");
-  const approval = contract.approval;
-  if (!approval || ["approval_ref", "approver", "persisted_ref", "current_version"].some((field) => !isPresent(approval[field])) || approval.approval_ref !== options.approvalRef || approval.persisted_ref !== options.persistedRef || approval.current_version !== options.contractVersion) fail("approval 记录不完整或不是当前合同版本");
-  const policy = contract.generation_policy;
-  if (policy?.mode !== "initialize-only" || policy?.existing_target !== "unsupported" || policy?.old_project_migration !== "unsupported" || policy?.template_upgrade !== "unsupported") fail("generation_policy 不符合 initialize-only");
-  const coordinates = contract.maven_coordinates;
-  const coordinateValues = [coordinates?.group_id, coordinates?.project_version, coordinates?.parent?.group_id, coordinates?.parent?.artifact_id, coordinates?.parent?.version, coordinates?.yss_components_version];
-  const optionValues = [options.groupId, options.projectVersion, options.parentGroupId, options.parentArtifactId, options.parentVersion, options.yssComponentsVersion];
-  if (coordinateValues.some((value) => !isPresent(value)) || JSON.stringify(coordinateValues) !== JSON.stringify(optionValues)) fail("Maven 坐标与合同不一致");
-  if (coordinateValues.some((value) => !/^[A-Za-z0-9_.-]+$/.test(String(value)))) fail("Maven 坐标只能包含字母、数字、点、下划线和连字符");
-  const decisionPath = path.isAbsolute(contract.decision_ref) ? contract.decision_ref : path.resolve(path.dirname(contractFile), contract.decision_ref);
-  const decisionText = await readFile(decisionPath, "utf8").catch(() => fail(`架构决策文件不可读取: ${decisionPath}`));
-  if (sha256(decisionText) !== contract.decision_digest) fail("架构决策文件 digest 与合同不一致");
-  const document = parseDocument(decisionText, { maxAliasCount: 0, uniqueKeys: true });
-  if (document.errors.length) fail(`架构决策 YAML 无效: ${document.errors[0].message}`);
-  const decisionSet = document.toJS({ maxAliasCount: 0 });
-  if (decisionSet?.kind !== "scaffold-architecture-decisions" || decisionSet?.template !== false || decisionSet?.status !== "current") fail("架构决策文件必须是 current 的正式 scaffold-architecture-decisions 记录");
-  const decisions = decisionSet.decisions ?? [];
-  const decision = decisions.find((item) => item.decision_id === contract.decision_id);
-  if (!decision || decision.status !== "lifecycle-approved" || decision.confirmed_architecture !== "layered-mvc" || decision.project_id !== contract.project_name) fail("架构决策未批准、项目不匹配或不是 layered-mvc");
-  if (decision.platform_profile !== contract.profiles.platform || decision.architecture_profile !== contract.architecture_profile || decision.verification_database !== "h2" || decision.production_database !== "not-bound" || Object.hasOwn(decision, "database_profile") || JSON.stringify(decision.requested_capabilities) !== JSON.stringify(contract.module_profile.requested_capabilities) || JSON.stringify(decision.resolved_modules) !== JSON.stringify(contract.module_profile.resolved_modules)) fail("架构决策的 Profile 或模块闭包与脚手架合同不一致");
-  if (!decision.user_confirmation || Object.values(decision.user_confirmation).some((value) => !isPresent(value))) fail("架构决策缺少完整用户确认记录");
-  assertScaffoldUserDecision(decision);
-  validateArchitectureIdentity(scaffoldArchitectureIdentity(contract, sha256(contractText)));
-  return { contract, contractText, modules: resolved };
-}
-
-async function validateOutputLayout(outputDir, projectName) {
-  const target = path.join(path.resolve(outputDir), projectName);
-  const relative = path.relative(REPOSITORY_ROOT, path.resolve(outputDir));
-  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
-    const parts = relative.split(path.sep).filter(Boolean);
-    if (!(parts.length === 2 && parts[0] === "apps" && parts[1] === "backend")) fail("Harness 内后端脚手架输出父目录必须是 apps/backend");
-  }
-  const gitRoot = findGitRoot(target) || findGitRoot(outputDir) || REPOSITORY_ROOT;
-  const violation = gitSubmoduleScaffoldViolation(gitRoot, path.resolve(outputDir), projectName, { force: false }) || overlayMountViolation(gitRoot, target, { force: true });
-  if (violation) fail(violation);
-  if (await exists(target)) fail(`unsupported: 目标已存在 ${target}`);
-}
-
-export async function generate(options, { skillId = SKILL_ID, architectureProfile = "layered-mvc-service", finalize } = {}) {
-  if (!((skillId === SKILL_ID && architectureProfile === "layered-mvc-service") || (skillId === "yss-mvc-data-analysis-project-initializer" && architectureProfile === "mvc-data-analysis-v1"))) fail("unsupported MVC generator/Profile pair");
-  await validateOutputLayout(options.outputDir, options.projectName);
-  const { contract, contractText, modules } = await validateContract(options, skillId, architectureProfile);
-  const outputDir = path.resolve(options.outputDir);
-  await mkdir(outputDir, { recursive: true });
-  const staging = await mkdtemp(path.join(outputDir, `.${options.projectName}.staging-`));
-  const projectRoot = path.join(staging, options.projectName);
-  const packagePath = options.basePackage.replaceAll(".", "/");
-  try {
-    await mkdir(projectRoot, { recursive: true });
-    await put(projectRoot, "pom.xml", parentPom(contract, modules));
-    for (const module of modules) {
-      const moduleRoot = `${options.projectName}-${module}`;
-      await put(projectRoot, `${moduleRoot}/pom.xml`, modulePom(contract, module, modules));
-      await put(projectRoot, `${moduleRoot}/src/main/java/${packagePath}/${module.replaceAll("-", "/")}/package-info.java`, `/** ${module} mechanical package boundary. */\npackage ${options.basePackage}.${module.replaceAll("-", ".")};`);
-    }
-    const applicationClass = `${toUpperCamel(options.projectName)}Application`;
-    const serverRoot = `${options.projectName}-server`;
-    await put(projectRoot, `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`, `package ${options.basePackage};\n\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\n\n/** Mechanical Spring Boot entrypoint. */\n@SpringBootApplication\npublic class ${applicationClass} {\n    public static void main(String[] args) {\n        SpringApplication.run(${applicationClass}.class, args);\n    }\n}`);
-    await put(projectRoot, `${serverRoot}/src/main/resources/application.yml`, `spring:\n  application:\n    name: ${options.projectName}`);
-    await put(projectRoot, `${serverRoot}/src/main/resources/application-scaffold-local.yml`, localDatabaseConfiguration(options.projectName));
-    await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
-    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
-    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
-    const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
-    await cp(wrapper, projectRoot, { recursive: true });
-    await chmod(path.join(projectRoot, "mvnw"), 0o755);
-    if (finalize) await finalize({ projectRoot, contract, architectureIdentity: scaffoldArchitectureIdentity(contract, sha256(contractText)) });
-    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v${contract.schema_version} 合同生成。模块：${modules.join("、")}。不包含业务 API、SQL 或生产数据库绑定。\n\n本地运行需同时显式启用 Maven -Pscaffold-local 和 Spring scaffold-local Profile；测试独立使用 H2。生产数据库须由后续已批准存储工作单元接入。`);
-    const generatedFiles = [];
-    for (const entry of await fileEntries(projectRoot, new Set([".yss/scaffold-generation.json"]))) generatedFiles.push({ path: entry.relative, owner: "generator", sha256: rawSha256(await readFile(entry.target)) });
-    const architectureRuleset = `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`;
-    const downstream = {};
-    for (const skill of ["yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"]) downstream[skill] = (await treeDigest(path.join(REPOSITORY_ROOT, ".agents/skills", skill))).replace(/^sha256:/, "");
-    const manifest = {
-      schema_version: contract.schema_version,
-      kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
-      architecture_profile: contract.architecture_profile,
-      architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),
-      contract_id: contract.contract_id,
-      contract_version: contract.contract_version,
-      scaffold_request_id: contract.scaffold_request_id,
-      architecture_family: "layered-mvc",
-      generator_skill: skillId,
-      decision_id: contract.decision_id,
-      decision_digest: contract.decision_digest,
-      decision_ref: contract.decision_ref,
-      contract_digest: sha256(contractText),
-      contract_file_ref: path.resolve(options.contractFile),
-      approval_ref: options.approvalRef,
-      approver: contract.approval.approver,
-      lifecycle_approval_ref: contract.lifecycle_approval_ref,
-      compiler_draft_ref: contract.compiler_draft_ref,
-      persisted_ref: contract.persisted_ref,
-      current_version: contract.current_version,
-      allowed_write_paths: contract.allowed_write_paths,
-      expected_evidence_files: contract.expected_evidence_files,
-      profiles: contract.profiles,
-      module_profile: contract.module_profile,
-      maven_coordinates: contract.maven_coordinates,
-      maven_coordinates_source: "approved-contract",
-      project_name: contract.project_name,
-      base_package: contract.base_package,
-      bootstrap_main_class: `${options.basePackage}.${applicationClass}`,
-      bootstrap_main_source: `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`,
-      generation_mode: "controlled-generation",
-      completion_level: "generated",
-      generation_policy: contract.generation_policy,
-      verification_commands: COMMANDS,
-      generator: { id: skillId, template_digest: await treeDigest(SKILL_ROOT) },
-      ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] },
-      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
-      generated_at: new Date().toISOString()
-    };
-    await put(projectRoot, ".yss/scaffold-generation.json", JSON.stringify(manifest, null, 2));
-    await rename(projectRoot, path.join(outputDir, options.projectName));
-    await rm(staging, { recursive: true, force: true });
-    process.stdout.write(`${JSON.stringify({ status: "generated", project_root: path.join(outputDir, options.projectName), modules }, null, 2)}\n`);
-  } catch (error) {
-    await rm(staging, { recursive: true, force: true });
-    throw error;
-  }
-}
-
-async function main() {
-  try {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.help) { process.stdout.write("Use --project-name --base-package --output-dir and approved contract metadata. Local/test database is H2; production is not bound.\n"); return 0; }
-    await generate(options);
-    return 0;
-  } catch (error) {
-    process.stderr.write(`❌ MVC 脚手架生成失败: ${error.message}\n`);
-    return 1;
-  }
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await main();

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-/** 复用统一 Manifest v3 / Maven Wrapper 验证协议。 */
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-
-import { run as runUnifiedVerification } from "../../yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
-
-export async function run(projectRoot, evidenceDir, environment = process.env) {
-  return runUnifiedVerification(path.resolve(projectRoot), path.resolve(evidenceDir), environment);
-}
-
-async function main() {
-  const [projectRoot, evidenceDir] = process.argv.slice(2);
-  if (!projectRoot || !evidenceDir) {
-    process.stderr.write("用法: node run_scaffold_verification.mjs <project-root> <evidence-dir>\n");
-    return 1;
-  }
-  try {
-    const report = await run(projectRoot, evidenceDir);
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    return report.status === "passed" ? 0 : 1;
-  } catch (error) {
-    process.stderr.write(`${error.message}\n`);
-    return 1;
-  }
-}
-
-const currentFile = fileURLToPath(import.meta.url);
-if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) process.exitCode = await main();

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,174 +0,0 @@
-import { attachScaffoldDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
-import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
-import { spawnSync } from "node:child_process";
-import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import test from "node:test";
-import { fileURLToPath } from "node:url";
-
-const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
-const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
-const capabilityModules = {
-  basic: { capabilities: [], modules: ["server", "service", "repository"] },
-  adapter: { capabilities: ["external-integration"], modules: ["server", "service", "repository", "adapter"] },
-  client: { capabilities: ["published-client"], modules: ["server", "service", "repository", "client"] },
-  feign: { capabilities: ["feign-client"], modules: ["server", "service", "repository", "client", "feign-client"] },
-  combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
-};
-
-async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator", schemaVersion = 3 } = {}) {
-  const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
-  t.after(() => rm(root, { recursive: true, force: true }));
-  const output = path.join(root, "backend");
-  await mkdir(output);
-  let decisionText = `${JSON.stringify({ schema_version: 1, kind: "scaffold-architecture-decisions", template: false, status: "current", decisions: [{ decision_id: "scaffold-decision.demo-service", project_id: "demo-service", parent_project_id: null, status: "lifecycle-approved", recommended_architecture: "layered-mvc", recommendation_reasons: ["薄 CRUD 服务"], confirmed_architecture: "layered-mvc", override_reason: null, inheritance_mode: "root-default", inherited_from: null, platform_profile: "spring-boot-2.7-jdk8", architecture_profile: architectureProfile, verification_database: "h2", production_database: "not-bound", requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1, user_confirmation: { confirmed_by: "tester", channel: "test", confirmation_ref: "test://confirmation", confirmed_at: "2026-09-05T00:00:00Z", normalized_text: "确认使用 MVC" }, decision_inputs_digest: `sha256:${"1".repeat(64)}` }] }, null, 2)}\n`;
-  const decisionSet = JSON.parse(decisionText);
-  decisionSet.decisions = decisionSet.decisions.map((decision) => attachScaffoldDecisionFixture(path.join(root, "user-decision"), decision));
-  decisionText = JSON.stringify(decisionSet, null, 2) + "\n";
-  const decisionFile = path.join(root, "scaffold-architecture-decisions.yaml");
-  await writeFile(decisionFile, decisionText);
-  const contract = {
-    schema_version: schemaVersion,
-    kind: "project-scaffold-contract",
-    delivery_role: "backend",
-    scaffold_kind: "backend-layered-mvc",
-    repository_scope: "external-repository",
-    init_git: false,
-    contract_id: "scaffold.demo-service.v1",
-    contract_version: 1,
-    scaffold_request_id: "request.demo-service",
-    status: "approved",
-    compiler_draft_ref: "compiler://demo/1",
-    lifecycle_approval_ref: "approval://demo/1",
-    persisted_ref: "contract://demo/1",
-    current_version: 1,
-    implementation_repository: "external",
-    backend_repository: "external",
-    scaffold_status: "required",
-    project_name: "demo-service",
-    target_output_dir: output,
-    base_package: "com.yss.demo",
-    architecture_family: "layered-mvc", architecture_profile: architectureProfile,
-    generator_skill: skillId,
-    decision_ref: decisionFile,
-    decision_id: "scaffold-decision.demo-service",
-    decision_digest: digest(decisionText),
-    maven_coordinates: { group_id: "com.yss.demo", project_version: "1.0.0-SNAPSHOT", parent: { group_id: "com.yss.cloud", artifact_id: "yss-cloud-microservice", version: "2.0.0-SNAPSHOT" }, yss_components_version: "2.0.0-SNAPSHOT" },
-    profiles: { architecture: "layered-mvc", persistence: "mybatis-plus", verification_database: "h2", production_database: "not-bound", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" },
-    module_profile: { requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1 },
-    allowed_write_paths: ["."],
-    expected_evidence_files: [".yss/scaffold-generation.json"],
-    verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"],
-    approval: { approval_ref: "approval://demo/1", approver: "lifecycle", persisted_ref: "contract://demo/1", current_version: 1 },
-    work_unit: { id: "scaffold.demo", behavior: "project-scaffold", primary_skill: skillId, supporting_skills: ["yss-implementation-contract-compiler"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true },
-    generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }
-  };
-  const contractFile = path.join(root, "contract.json");
-  await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
-  const args = ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-file", contractFile, "--contract-id", contract.contract_id, "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", contract.compiler_draft_ref, "--persisted-ref", contract.persisted_ref, "--group-id", "com.yss.demo", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.cloud", "--parent-artifact-id", "yss-cloud-microservice", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
-  return { root, output, decisionFile, contractFile, contract, args, project: path.join(output, "demo-service") };
-}
-
-test("数据分析初始化生成 H2 六模块和独立治理信封", async (t) => {
-  const skillId = "yss-mvc-data-analysis-project-initializer";
-  const data = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", skillId, profile: { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] } });
-  const context = "---\ncontext_schema_version: 1\n---\n# 业务上下文\n\n## 业务术语\n\n| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |\n|---|---|---|---|---|\n";
-  await writeFile(path.join(data.root, "context-handoff.md"), context);
-  data.contract.context_handoff_ref = "context-handoff.md";
-  data.contract.context_handoff_digest = digest(context);
-  await writeFile(data.contractFile, JSON.stringify(data.contract));
-  const initializer = path.resolve(path.dirname(script), `../../${skillId}/scripts/generate_project.mjs`);
-  const result = spawnSync(process.execPath, [initializer, ...data.args], { encoding: "utf8" });
-  assert.equal(result.status, 0, result.stderr);
-  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
-  assert.equal(manifest.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
-  assert.equal(manifest.generator_skill, skillId);
-  assert.equal(await readFile(path.join(data.project, "CONTEXT.md"), "utf8"), context);
-  await stat(path.join(data.project, ".git"));
-  await stat(path.join(data.output, "skillUtils/skills-lock.json"));
-  assert.ok(!manifest.ownership.generated_files.some((entry) => entry.path.startsWith(".git/")));
-  const core = await readFile(path.join(data.project, "demo-service-core/pom.xml"), "utf8");
-  assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
-});
-
-test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
-  const data = await fixture(t);
-  for (const args of [["--database", "mysql"], ["--with-mock"]]) {
-    const result = spawnSync(process.execPath, [script, ...data.args, ...args], { encoding: "utf8" });
-    assert.notEqual(result.status, 0);
-    await assert.rejects(stat(data.project), { code: "ENOENT" });
-  }
-});
-
-test("统一 Project Scaffold Contract v4 可生成 Layered MVC 后端并保留 v4 Manifest", async (t) => {
-  const data = await fixture(t, { schemaVersion: 4 });
-  data.contract.current_version = true;
-  await writeFile(data.contractFile, JSON.stringify(data.contract));
-  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
-  assert.equal(result.status, 0, result.stderr);
-  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
-  assert.equal(manifest.schema_version, 4);
-});
-
-test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
-  const data = await fixture(t);
-  const generated = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
-  assert.equal(generated.status, 0, generated.stderr);
-  for (const phase of ["validate", "test", "package"]) {
-    const result = spawnSync(path.join(data.project, "mvnw"), ["-o", phase], { cwd: data.project, encoding: "utf8", timeout: 60_000 });
-    t.diagnostic(`./mvnw -o ${phase}: exit=${result.status}; ${result.error?.message ?? ""}`);
-    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
-  }
-});
-
-for (const database of ["h2"]) {
-  test(`生成 ${database} 基础 Profile`, async (t) => {
-    const data = await fixture(t, { database });
-    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
-    assert.equal(result.status, 0, result.stderr);
-    const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
-    assert.equal(manifest.schema_version, 3);
-    assert.equal(manifest.architecture_family, "layered-mvc");
-    assert.equal(manifest.profiles.verification_database, database);
-    assert.equal(manifest.profiles.production_database, "not-bound");
-    assert.equal(manifest.architecture_identity.architecture_profile, "layered-mvc-service");
-    const config = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application.yml"), "utf8");
-    assert.doesNotMatch(config, /datasource|profiles|jdbc:/);
-    const local = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application-scaffold-local.yml"), "utf8");
-    assert.match(local, /jdbc:h2:mem:/);
-    assert.deepEqual(manifest.module_profile.resolved_modules, capabilityModules.basic.modules);
-    await stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/DemoServiceApplication.java"));
-    await assert.rejects(stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/server/controller")), { code: "ENOENT" });
-  });
-}
-
-for (const [name, profile] of Object.entries(capabilityModules)) {
-  test(`能力闭包 ${name}`, async (t) => {
-    const data = await fixture(t, { profile });
-    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
-    assert.equal(result.status, 0, result.stderr);
-    const pom = await readFile(path.join(data.project, "pom.xml"), "utf8");
-    for (const module of profile.modules) assert.match(pom, new RegExp(`<module>demo-service-${module}</module>`));
-    for (const module of ["adapter", "client", "feign-client"].filter((item) => !profile.modules.includes(item))) assert.doesNotMatch(pom, new RegExp(`<module>demo-service-${module}</module>`));
-  });
-}
-
-test("选择缺失、digest 漂移和非空目标均阻断", async (t) => {
-  const missing = await fixture(t);
-  missing.contract.decision_id = "decision.missing";
-  await writeFile(missing.contractFile, `${JSON.stringify(missing.contract)}\n`);
-  assert.notEqual(spawnSync(process.execPath, [script, ...missing.args], { encoding: "utf8" }).status, 0);
-
-  const drift = await fixture(t);
-  drift.contract.decision_digest = `sha256:${"0".repeat(64)}`;
-  await writeFile(drift.contractFile, `${JSON.stringify(drift.contract)}\n`);
-  assert.notEqual(spawnSync(process.execPath, [script, ...drift.args], { encoding: "utf8" }).status, 0);
-
-  const existing = await fixture(t);
-  await mkdir(existing.project);
-  const blocked = spawnSync(process.execPath, [script, ...existing.args], { encoding: "utf8" });
-  assert.notEqual(blocked.status, 0);
-  assert.match(blocked.stderr, /目标已存在/);
-});

package/template/.qoder/skills/yss-mvc-data-analysis-project-initializer/SKILL.md

@@ -1,22 +0,0 @@
----
-name: yss-mvc-data-analysis-project-initializer
-description: 在生命周期批准的初始化合同下创建独立 Git 管理的数据分析 project-instance；固定 mvc-data-analysis-v1 六模块、Java 8 和本地测试 H2。
----
-
-# 数据分析 MVC 项目初始化
-
-这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。旧 `yss-mvc-scaffold-generator` 已退役且不提供自动别名。
-
-## 执行合同
-
-- 必须有生命周期批准且当前的 schema v3 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器及已批准的架构决策。
-- 固定 server/core/client/repository/adapter/feign-client；core 是薄应用层，规则见 `docs/agents/backend-architecture-profiles.md`。不生成业务接口、SQL、DDL、Mock、生产数据库配置或额外数据源。
-- `verification_database=h2` / `production_database=not-bound`；Java 8 / Boot 2.7 / javax。目标不存在，禁止覆盖、迁移、自动提交和推送。
-- 合同必须包含 `context_handoff_ref`、`context_handoff_digest`：批准交接的完整根 CONTEXT.md（含 schema frontmatter），不得用跨仓路径替代本仓词汇表。初始化只复制已确认内容，不创造业务术语；父项目只保留服务引用和 handoff 证据。
-- `allowed_write_paths` 必须覆盖目标项目及同级 skillUtils。已有 skillUtils 锁不匹配即 blocked，不替换别的项目正在使用的工具包。
-
-## 命令与结果
-
-`node scripts/generate_project.mjs` 使用通用 MVC 生成器相同的批准合同与 Maven 坐标参数（`--output-dir` 是父容器）；无 `--database`、`--with-mock` 或交互选项。
-
-输出独立 project-instance、初始化但未提交的 main Git、生命周期资产、完整锁定 skillUtils、架构身份及 Manifest。使用共享 `run_scaffold_verification.mjs <project> <evidence>` 实跑三条 Wrapper 命令；只在实际成功后报告 empty-scaffold-verified。Profile 仍须独立首切片 fixture 达标才能晋升 supported。