create-yss-spec 2.1.4 → 2.1.6

package/template/.qoder/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.py

@@ -1,155 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""在生成项目根目录实际执行 YSS 脚手架的固定验证命令并留证。"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import subprocess
-import sys
-import time
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Dict, List
-
-
-COMMANDS = ("validate", "test", "package")
-
-
-def iso_now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def write_text(path: Path, content: str) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content, encoding="utf-8", errors="replace")
-
-
-def run(project_root: Path, evidence_dir: Path) -> Dict[str, object]:
-    wrapper = project_root / "mvnw"
-    if not wrapper.is_file():
-        raise FileNotFoundError(f"项目根目录缺少 Maven wrapper: {wrapper}")
-    manifest_path = project_root / ".yss" / "scaffold-generation.json"
-    if not manifest_path.is_file():
-        raise FileNotFoundError(f"项目根目录缺少脚手架生成元数据清单: {manifest_path}")
-    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-    required_manifest_fields = [
-        "schema_version",
-        "contract_id",
-        "contract_version",
-        "slice_id",
-        "approval_ref",
-        "approver",
-        "lifecycle_approval_ref",
-        "router_draft_ref",
-        "persisted_ref",
-        "contract_file_ref",
-        "current_version",
-        "allowed_write_paths",
-        "expected_evidence_files",
-        "verification_commands",
-        "generation_mode",
-    ]
-    missing_manifest_fields = [
-        field for field in required_manifest_fields if manifest.get(field) in (None, "")
-    ]
-    if manifest.get("generation_mode") != "controlled-generation" or missing_manifest_fields:
-        raise ValueError(
-            "脚手架生成元数据清单不完整或不是 controlled-generation: "
-            + ", ".join(missing_manifest_fields)
-        )
-    if manifest["current_version"] != manifest["contract_version"]:
-        raise ValueError("脚手架生成元数据清单不是当前合同版本")
-    if manifest["verification_commands"] != [
-        "./mvnw validate",
-        "./mvnw test",
-        "./mvnw package",
-    ]:
-        raise ValueError("脚手架生成元数据清单验证命令不符合固定合同")
-
-    evidence_dir.mkdir(parents=True, exist_ok=True)
-    command_results: List[Dict[str, object]] = []
-    for phase in COMMANDS:
-        command = f"./mvnw {phase}"
-        stdout_path = evidence_dir / f"mvnw-{phase}.stdout.log"
-        stderr_path = evidence_dir / f"mvnw-{phase}.stderr.log"
-        started_at = iso_now()
-        started = time.monotonic()
-        try:
-            completed = subprocess.run(
-                [str(wrapper), phase],
-                cwd=project_root,
-                text=True,
-                capture_output=True,
-                check=False,
-            )
-            exit_code = completed.returncode
-            stdout = completed.stdout
-            stderr = completed.stderr
-        except OSError as exception:
-            exit_code = 127
-            stdout = ""
-            stderr = str(exception)
-        duration_ms = round((time.monotonic() - started) * 1000, 3)
-        write_text(stdout_path, stdout)
-        write_text(stderr_path, stderr)
-        command_results.append(
-            {
-                "command": command,
-                "phase": phase,
-                "exit_code": exit_code,
-                "duration_ms": duration_ms,
-                "started_at": started_at,
-                "executed_at": iso_now(),
-                "stdout_ref": str(stdout_path),
-                "stderr_ref": str(stderr_path),
-            }
-        )
-
-    return {
-        "verification_mode": "controlled-generation",
-        "project_root": str(project_root),
-        "scaffold_manifest_ref": str(manifest_path),
-        "generated_at": iso_now(),
-        "status": "passed" if all(item["exit_code"] == 0 for item in command_results) else "failed",
-        "commands": command_results,
-    }
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="运行 YSS 脚手架真实验证命令")
-    parser.add_argument("--project-root", required=True, help="已生成后端项目的根目录")
-    parser.add_argument("--evidence-dir", required=True, help="验证日志和 JSON 报告目录")
-    args = parser.parse_args()
-
-    project_root = Path(args.project_root).resolve()
-    evidence_dir = Path(args.evidence_dir).resolve()
-    report_path = evidence_dir / "scaffold-verification.json"
-    try:
-        report = run(project_root, evidence_dir)
-    except Exception as exception:
-        report = {
-            "verification_mode": "controlled-generation",
-            "project_root": str(project_root),
-            "generated_at": iso_now(),
-            "status": "failed",
-            "error": str(exception),
-            "commands": [],
-        }
-        report_path.parent.mkdir(parents=True, exist_ok=True)
-        report_path.write_text(
-            json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
-        )
-        print(f"❌ 脚手架验证无法执行: {exception}", file=sys.stderr)
-        return 1
-
-    report_path.write_text(
-        json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
-    )
-    print(f"{report['status']}: {report_path}")
-    return 0 if report["status"] == "passed" else 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/template/.qoder/skills/yss-design-system/scripts/validate-frontmatter.py

@@ -1,50 +0,0 @@
-#!/usr/bin/env python3
-"""Validate the yss-design-system skill frontmatter without third-party deps."""
-
-from pathlib import Path
-import re
-import sys
-
-
-ROOT = Path(__file__).resolve().parents[1]
-SKILL = ROOT / "SKILL.md"
-
-
-def main() -> int:
-    text = SKILL.read_text(encoding="utf-8")
-    match = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
-    if not match:
-        print("Invalid SKILL.md frontmatter block", file=sys.stderr)
-        return 1
-
-    fields: dict[str, str] = {}
-    for line in match.group(1).splitlines():
-        if not line.strip():
-            continue
-        key, sep, value = line.partition(":")
-        if not sep:
-            print(f"Invalid frontmatter line: {line}", file=sys.stderr)
-            return 1
-        fields[key.strip()] = value.strip()
-
-    expected = {"name", "description"}
-    if set(fields) != expected:
-        print(f"Expected keys {sorted(expected)}, got {sorted(fields)}", file=sys.stderr)
-        return 1
-
-    name = fields["name"]
-    if not re.match(r"^[a-z0-9-]+$", name):
-        print(f"Invalid skill name: {name}", file=sys.stderr)
-        return 1
-
-    description = fields["description"]
-    if not description or len(description) > 1024:
-        print("Description must be present and <= 1024 chars", file=sys.stderr)
-        return 1
-
-    print(f"{name} frontmatter ok")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/template/.qoder/skills/yss-source-index/scripts/refresh-yss-skill-index.py

@@ -1,371 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import datetime as dt
-import os
-import subprocess
-from pathlib import Path
-
-DEFAULT_SKILLS_ROOT = Path(__file__).resolve().parents[2]
-SKILLS_ROOT = Path(os.environ.get("YSS_SKILLS_ROOT", str(DEFAULT_SKILLS_ROOT))).expanduser()
-
-BACKEND_SKILLS = {
-    "yss-cache": [
-        "yss-microservice-components/yss-component-cache-parent",
-    ],
-    "yss-mybatis": [
-        "yss-microservice-components/yss-component-persistence",
-    ],
-    "yss-dto": [
-        "yss-microservice-components/yss-component-dto",
-    ],
-    "yss-audit-log": [
-        "yss-microservice-components/yss-component-audit-log",
-    ],
-    "yss-excel-mvc": [
-        "yss-microservice-components/yss-component-excel-mvc",
-        "yss-microservice-components/yss-component-excel-starter",
-    ],
-    "yss-distributed-id": [
-        "yss-microservice-components/yss-component-distributed-id",
-        "yss-microservice-components/yss-component-leaf",
-    ],
-    "yss-jdbc": [
-        "yss-microservice-components/yss-component-jdbc",
-    ],
-    "yss-dictionary": [
-        "yss-microservice-components/yss-component-dictionary-parent",
-    ],
-    "yss-log": [
-        "yss-microservice-components/yss-component-log-starter",
-    ],
-    "yss-resilience4j": [
-        "yss-microservice-components/yss-component-resilience4j-starter",
-    ],
-    "yss-taskflow": [
-        "yss-microservice-components/yss-component-taskflow",
-    ],
-    "yss-validation": [
-        "yss-microservice-components/yss-component-validation-engine-parent",
-        "yss-microservice-components/yss-component-validation-jsr303",
-    ],
-    "yss-security-algorithm": [
-        "yss-microservice-components/yss-component-security-algorithm",
-    ],
-    "yss-userinfo": [
-        "yss-microservice-components/yss-component-userinfo-starter",
-    ],
-    "yss-variable": [
-        "yss-microservice-components/yss-component-variable",
-    ],
-    "yss-exception": [
-        "yss-microservice-components/yss-component-exception",
-    ],
-    "yss-valuation": [
-        "yss-microservice-components/yss-component-valuation",
-    ],
-}
-
-FRONTEND_DOCS = {
-    "components": "http://192.168.164.27:3200/components",
-    "hooks": "http://192.168.164.27:3200/hooks",
-    "skills": "http://192.168.164.27:3200/skills",
-}
-
-FRONTEND_SKILLS = {
-    "yss-ui": ["components", "hooks", "skills"],
-    "yss-components": ["components"],
-    "yss-hook": ["hooks"],
-    "yss-page-module-development": ["components", "hooks", "skills"],
-    "yss-use-table-height": ["hooks"],
-    "yss-use-tree-height": ["hooks"],
-}
-
-KEY_NAME_PARTS = (
-    "Audit",
-    "Cache",
-    "Clear",
-    "Command",
-    "Configuration",
-    "Controller",
-    "DTO",
-    "Data",
-    "Enable",
-    "Excel",
-    "Handler",
-    "Interceptor",
-    "Jdbc",
-    "Mapper",
-    "Mybatis",
-    "Page",
-    "Properties",
-    "Query",
-    "Repository",
-    "Request",
-    "Response",
-    "Result",
-    "Update",
-    "Aspect",
-    "Leaf",
-    "Id",
-    "Dir",
-    "Dic",
-    "Dictionary",
-    "File",
-    "Upload",
-    "Log",
-    "Message",
-    "Mail",
-    "Liquibase",
-    "Circuit",
-    "Breaker",
-    "Sql",
-    "Tpl",
-    "Tag",
-    "Task",
-    "Flow",
-    "Report",
-    "Validation",
-    "Validator",
-    "Security",
-    "Crypto",
-    "User",
-    "Variable",
-    "Quality",
-    "Search",
-    "Similarity",
-    "Scheduler",
-    "Runner",
-    "Duck",
-    "Dynamic",
-    "Factory",
-    "Client",
-    "Feign",
-    "Gateway",
-    "Convertor",
-    "Adapter",
-    "Advice",
-    "Bridge",
-    "Route",
-    "Uploader",
-    "Sftp",
-    "Minio",
-    "Parser",
-    "Express",
-    "Rule",
-    "Template",
-    "Generator",
-    "Importer",
-    "Engine",
-    "Event",
-    "Submitter",
-    "Executor",
-    "Context",
-    "Status",
-    "Type",
-    "State",
-)
-
-DOC_NAMES = {"README.md", "readme.md", "HELP.md", "TECHNICAL_DESIGN.md"}
-
-
-def has_component_root(path: Path) -> bool:
-    return (path / "yss-microservice-components").is_dir()
-
-
-def source_root_candidates() -> list[Path]:
-    cwd = Path.cwd().resolve()
-    home = Path.home()
-    candidates: list[Path] = [cwd, *cwd.parents]
-    candidates.extend(
-        [
-            home / "Documents/yss-project/yss-cloud-microservice",
-            home / "Documents/yss-project",
-            home / "Projects/yss-cloud-microservice",
-            home / "Projects",
-        ]
-    )
-    for base in [home / "Projects", home / "Documents", home / "Documents/yss-project"]:
-        if base.is_dir():
-            candidates.extend(path for path in base.glob("*") if path.is_dir())
-    return candidates
-
-
-def resolve_source_root() -> Path:
-    explicit = os.environ.get("YSS_SOURCE_ROOT")
-    if explicit:
-        root = Path(explicit).expanduser().resolve()
-        if not has_component_root(root):
-            raise SystemExit(
-                "YSS_SOURCE_ROOT must point to the repository root containing "
-                f"`yss-microservice-components`: {root}"
-            )
-        return root
-
-    for candidate in source_root_candidates():
-        candidate = candidate.expanduser().resolve()
-        if has_component_root(candidate):
-            return candidate
-
-    raise SystemExit(
-        "Could not find a YSS source repository containing `yss-microservice-components`. "
-        "Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun."
-    )
-
-
-SOURCE_ROOT = resolve_source_root()
-
-
-def git_source_state() -> tuple[str, str]:
-    try:
-        commit = subprocess.check_output(
-            ["git", "-C", str(SOURCE_ROOT), "rev-parse", "HEAD"],
-            text=True,
-        ).strip()
-        status = subprocess.check_output(
-            ["git", "-C", str(SOURCE_ROOT), "status", "--porcelain"],
-            text=True,
-        )
-        return commit, "dirty" if status.strip() else "clean"
-    except (OSError, subprocess.CalledProcessError):
-        return "unavailable", "unknown"
-
-
-SOURCE_COMMIT, SOURCE_WORKTREE_STATE = git_source_state()
-
-
-def rel(path: Path) -> str:
-    try:
-        return str(path.relative_to(SOURCE_ROOT))
-    except ValueError:
-        return str(path)
-
-
-def collect_files(paths: list[Path]) -> dict[str, list[Path]]:
-    docs: list[Path] = []
-    poms: list[Path] = []
-    java: list[Path] = []
-    for base in paths:
-        if not base.exists():
-            continue
-        for path in base.rglob("*"):
-            if not path.is_file():
-                continue
-            if path.name in DOC_NAMES:
-                docs.append(path)
-            elif path.name == "pom.xml":
-                poms.append(path)
-            elif path.suffix == ".java" and "/src/main/java/" in str(path):
-                java.append(path)
-    return {
-        "docs": sorted(docs),
-        "poms": sorted(poms),
-        "java": sorted(java),
-    }
-
-
-def interesting_java(paths: list[Path]) -> list[Path]:
-    selected = []
-    for path in paths:
-        name = path.stem
-        if any(part in name for part in KEY_NAME_PARTS):
-            selected.append(path)
-    return selected[:120]
-
-
-def write_backend_index(skill: str, subpaths: list[str], generated_at: str) -> None:
-    bases = [SOURCE_ROOT / subpath for subpath in subpaths]
-    files = collect_files(bases)
-    selected_java = interesting_java(files["java"])
-    target_dir = SKILLS_ROOT / skill / "references"
-    target_dir.mkdir(parents=True, exist_ok=True)
-    target = target_dir / "source-index.md"
-
-    lines = [
-        f"# {skill} Source Index",
-        "",
-        f"Generated: {generated_at}",
-        f"Source commit: `{SOURCE_COMMIT}`",
-        f"Source worktree: `{SOURCE_WORKTREE_STATE}`",
-        "Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.",
-        "",
-        "This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.",
-        "",
-        "Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.",
-        "",
-        "## Component Path Hints",
-        "",
-    ]
-    for base in bases:
-        status = "existed when indexed" if base.exists() else "missing when indexed"
-        lines.append(f"- `{rel(base)}` ({status})")
-
-    lines += ["", "## Documentation Files", ""]
-    if files["docs"]:
-        lines.extend(f"- `{rel(path)}`" for path in files["docs"])
-    else:
-        lines.append("- No component documentation files found.")
-
-    lines += ["", "## Maven Modules", ""]
-    if files["poms"]:
-        lines.extend(f"- `{rel(path.parent)}`" for path in files["poms"])
-    else:
-        lines.append("- No Maven modules found.")
-
-    lines += ["", "## Key Java Entry Points", ""]
-    if selected_java:
-        lines.extend(f"- `{rel(path)}`" for path in selected_java)
-    else:
-        lines.append("- No key Java entry points matched the configured name patterns.")
-
-    lines += [
-        "",
-        "## Recommended Next Reads",
-        "",
-        "- Start with the documentation files above when learning component usage.",
-        "- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.",
-        "- Prefer existing component extension points over rewriting framework logic in business modules.",
-        "",
-    ]
-    target.write_text("\n".join(lines), encoding="utf-8")
-
-
-def write_frontend_docs(skill: str, doc_keys: list[str], generated_at: str) -> None:
-    target_dir = SKILLS_ROOT / skill / "references"
-    if not (SKILLS_ROOT / skill).exists():
-        return
-    target_dir.mkdir(parents=True, exist_ok=True)
-    target = target_dir / "frontend-docs.md"
-    lines = [
-        f"# {skill} Frontend Documentation",
-        "",
-        f"Generated: {generated_at}",
-        "",
-        "Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.",
-        "",
-    ]
-    for key in doc_keys:
-        lines.append(f"- {key}: {FRONTEND_DOCS[key]}")
-    lines += [
-        "",
-        "When documentation and local code differ, inspect the current project code before editing and prefer established local usage.",
-        "",
-    ]
-    target.write_text("\n".join(lines), encoding="utf-8")
-
-
-def main() -> int:
-    generated_at = dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
-    for skill, subpaths in BACKEND_SKILLS.items():
-        write_backend_index(skill, subpaths, generated_at)
-    refresh_frontend = os.environ.get("YSS_REFRESH_FRONTEND", "true").lower() not in {"0", "false", "no"}
-    if refresh_frontend:
-        for skill, doc_keys in FRONTEND_SKILLS.items():
-            write_frontend_docs(skill, doc_keys, generated_at)
-    frontend_count = len(FRONTEND_SKILLS) if refresh_frontend else 0
-    print(f"Updated {len(BACKEND_SKILLS)} backend indexes and {frontend_count} frontend doc references.")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())