create-yss-spec 2.1.15 → 2.2.1

package/template/.cursor/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -64,7 +64,7 @@ node scripts/generate_scaffold.mjs \
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若仓库已经存在相同工程，先核对覆盖范围。
 - 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -5,6 +5,12 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+import {
+  findGitRoot,
+  gitSubmoduleScaffoldViolation,
+  overlayMountViolation
+} from "../../../../scripts/lib/repository-scope-policy.mjs";
+
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
@@ -87,11 +93,28 @@ class ScaffoldGenerator {
     this.scaffoldContract = undefined;
   }
 
+  gitRootForOutput() {
+    return findGitRoot(this.finalProjectRoot) || findGitRoot(this.outputDir) || REPOSITORY_ROOT;
+  }
+
+  refuseGitlinkAsRegularDirectory(gitRoot, target) {
+    const overlay = overlayMountViolation(gitRoot, target, { force: true });
+    if (overlay) fail(overlay);
+  }
+
   async generate() {
     await this.validateHarnessOutputLayout();
-    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    const gitRoot = this.gitRootForOutput();
+    const gitlinkViolation = gitSubmoduleScaffoldViolation(gitRoot, this.outputDir, this.projectName, { force: this.options.force });
+    if (gitlinkViolation) fail(gitlinkViolation);
+    this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+    const targetExists = await exists(this.finalProjectRoot);
+    if (targetExists) {
+      this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+      if (!this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    }
     await this.validateContractMetadata();
-    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    if (targetExists && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
     await mkdir(this.outputDir, { recursive: true });
     const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
     this.projectRoot = path.join(stagingRoot, this.projectName);
@@ -101,7 +124,11 @@ class ScaffoldGenerator {
       this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
       await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
       let backupPath;
-      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      if (await exists(this.finalProjectRoot)) {
+        this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+        backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`);
+        await rename(this.finalProjectRoot, backupPath);
+      }
       await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
       console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
       if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,11 +1,14 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
+import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
+import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
@@ -21,6 +24,55 @@ test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t
 
 test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
 
+test("拒绝覆盖 .gitmodules 登记的 git-submodule 挂载点", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const superproject = path.join(data.root, "harness");
+  const output = path.join(superproject, "apps/backend");
+  await mkdir(path.join(output, "demo-service"), { recursive: true });
+  await writeFile(path.join(superproject, ".gitmodules"), "[submodule \"demo-service\"]\n\tpath = apps/backend/demo-service\n\turl = https://example.invalid/demo-service.git\n");
+  const contractFile = path.join(data.root, "gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  assert.equal(result.code, 1, result.stderr);
+  assert.match(`${result.stdout}\n${result.stderr}`, /gitlink 不得由脚手架覆盖/);
+});
+
+test("拒绝在 detached HEAD 子仓工作树内当成普通目录生成", async (t) => {
+  const data = await fixture();
+  const detached = makeGitlinkFixture({ checkout: "detached-head" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => detached.cleanup());
+  const output = path.join(detached.superproject, detached.mount);
+  const contractFile = path.join(data.root, "detached-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "nested-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /detached HEAD 不得当成普通目录写入/);
+  assert.equal(existsSync(path.join(output, "nested-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("staging") || name === "nested-service"), false);
+});
+
+test("--force 覆盖真实 gitlink 不得走普通目录覆盖路径", async (t) => {
+  const data = await fixture();
+  const empty = makeGitlinkFixture({ checkout: "empty-gitlink" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => empty.cleanup());
+  const output = path.join(empty.superproject, "apps/backend");
+  const contractFile = path.join(data.root, "empty-gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "billing-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /--force 不得把 git-submodule 挂载点当成普通目录覆盖|gitlink 不得/);
+  assert.equal(existsSync(path.join(output, "billing-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("backup")), false);
+  assert.equal(gitLsFilesStage(empty.superproject, empty.mount)?.mode, GITLINK_MODE);
+});
+
 test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });

package/template/.cursor/skills/yss-design-system/SKILL.md

@@ -89,7 +89,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
 | 原型阶段的 Ant Design v6 组件 / token / demo 查询 | `yss-antd-design`（只用于原型设计构建；前端落地改用 `yss-ui`） |
 | Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
-| API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
+| API 契约 / 接入 | `yss-openapi-governance` / `yss-api-integration` |
 
 ## 更新设计系统