create-yss-spec 3.3.1 → 3.3.4

package/template/.trae/skills/yss-security-algorithm/references/source-index.md

@@ -1,35 +0,0 @@
-# yss-security-algorithm Source Index
-
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
-Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-
-This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. 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
-
-- `yss-microservice-components/yss-component-security-algorithm` (existed when indexed)
-
-## Documentation Files
-
-- No component documentation files found.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-security-algorithm`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/CryptoType.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/config/DefaultJwtConfiguration.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/jose/KeyGeneratorUtils.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/util/SecurityCryptoUtil.java`
-
-## 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.

package/template/.trae/skills/yss-skill-source-index-refresh/SKILL.md

@@ -1,66 +0,0 @@
----
-name: yss-skill-source-index-refresh
-description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
----
-
-# YSS Skill Source Index Refresh
-
-Use this maintenance skill to keep YSS skills grounded in current source and documentation.
-
-中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
-
-## Source Location Policy
-
-- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
-- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
-- Frontend YSS UI components: `http://192.168.164.27:3200/components`
-- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
-- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
-
-## Refresh Workflow
-
-Run:
-
-```bash
-export YSS_SKILLS_ROOT="/path/to/.agents/skills"
-export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
-node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs"
-```
-
-Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
-Use `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis` (comma-separated) to refresh only selected backend indexes and avoid unrelated component churn.
-
-The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
-
-中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
-
-If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
-
-## Output Contract
-
-Generated source indexes should contain:
-
-- generated timestamp and trace-only source Git commit
-- component-relative tree hashes and component-scoped worktree state
-- component directories and documentation files
-- Maven modules
-- source file hashes and relocatable paths
-- for capability-sensitive components, concise public signatures, configuration keys/defaults, conditional activation and capability boundaries extracted from source
-- for other components, key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
-- recommended next reads for Agent when performing implementation or troubleshooting
-
-Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
-
-## Freshness Gate
-
-Before exact class/config/security guidance, compare each indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
-
-中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
-
-## After Refresh
-
-Validate the migrated Node helper with:
-
-```bash
-node --test "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs"
-```

package/template/.trae/skills/yss-skill-source-index-refresh/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS Skill Source Index Refresh"
-  short_description: "Locate sources and refresh YSS skill indexes"
-  default_prompt: "Refresh YSS skill indexes from yss-cloud-microservice and YSS UI docs."

package/template/.trae/skills/yss-skill-source-index-refresh/references/source-location.md

@@ -1,19 +0,0 @@
-# YSS Source Location Policy
-
-YSS skill references may mention paths such as `yss-microservice-components/yss-component-dto`. Treat these as source path hints, not guaranteed filesystem locations.
-
-## Lookup Order
-
-1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
-2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
-   Compare every indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
-3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
-4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
-
-## For Skill Authors
-
-- Say "source path hints" instead of "source root" unless you have verified the directory in the current environment.
-- Keep generated indexes useful for search, but do not require agents to open those exact paths.
-- Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
-- Keep full production source out of skill `assets/`; generate concise signatures, activation conditions and file hashes instead.
-- When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.

package/template/.trae/skills/yss-skill-source-index-refresh/references/source-map-config.md

@@ -1,29 +0,0 @@
-# YSS Source Index Mapping
-
-The refresh script maps component source path hints to skill references. These paths are relative to the detected or configured `YSS_SOURCE_ROOT`; they are not guaranteed to exist in every workspace.
-
-中文说明：这个文件记录“哪个组件源码目录生成到哪个 skill 的引用索引”，方便你以后维护映射关系。
-
-| Skill | Backend source path hints |
-| --- | --- |
-| `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-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `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-exception` | `yss-microservice-components/yss-component-exception` |
-
-Frontend docs are written to these skills:
-
-| Skill | Frontend references |
-| --- | --- |
-| `yss-ui` | components, hooks, skills docs |
-| `yss-components` | components docs |
-| `yss-hook` | hooks docs |
-| `yss-use-table-height` | hooks docs |
-| `yss-use-tree-height` | hooks docs |

package/template/.trae/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs

@@ -1,394 +0,0 @@
-#!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { execFileSync } from "node:child_process";
-import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const BACKEND = {
-  "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-resilience4j": ["yss-microservice-components/yss-component-resilience4j-starter"],
-  "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-exception": ["yss-microservice-components/yss-component-exception"],
-};
-
-const FRONTEND = {
-  "yss-ui": ["components", "hooks", "skills"],
-  "yss-components": ["components"],
-  "yss-hook": ["hooks"],
-  "yss-ui-business-page-generation": ["components", "hooks", "skills"],
-  "yss-use-table-height": ["hooks"],
-  "yss-use-tree-height": ["hooks"],
-};
-
-const URLS = {
-  components: "http://192.168.164.27:3200/components",
-  hooks: "http://192.168.164.27:3200/hooks",
-  skills: "http://192.168.164.27:3200/skills",
-};
-
-const KEYS = [
-  "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",
-];
-
-const DOCS = new Set(["README.md", "readme.md", "HELP.md", "TECHNICAL_DESIGN.md"]);
-const SKIPPED_DIRECTORIES = new Set([".git", "node_modules", "target", "build", "out", "${project.build.directory}"]);
-
-const MYBATIS_CAPABILITIES = [
-  {
-    title: "Repository abstractions",
-    sources: [
-      {
-        suffix: "/support/BaseRepository.java",
-        patterns: [/public interface BaseRepository/, /int (insert|insertSelective|insertList|updateList|updateListSelective)\(/],
-      },
-      {
-        suffix: "/support/BasePlusRepository.java",
-        patterns: [/public interface BasePlusRepository/, /insertBatchSomeColumn/],
-      },
-    ],
-  },
-  {
-    title: "Pagination and activation",
-    sources: [
-      { suffix: "/aop/EntityQueryAspect.java", patterns: [/@Around\(/, /PageHelper\.offsetPage/] },
-      { suffix: "/config/PageQueryEntityConfigration.java", patterns: [/@ConditionalOnProperty/] },
-      {
-        suffix: "/YssMybatisMapperProperties.java",
-        patterns: [
-          /@ConfigurationProperties/,
-          /private (String mapperLocation|String mapperScan|Integer batchSize|String dbType|PageHelper pageHelper|MybatisPlusPagination mybatisPlusPagination)/,
-          /public static class (PageHelper|MybatisPlusPagination)/,
-          /private Boolean enabled/,
-        ],
-      },
-      {
-        suffix: "/config/MapperConfiguration.java",
-        patterns: [/new PageInterceptor\(/, /new PaginationInnerInterceptor\(/, /setBatchSize\(/, /setDbType\(/],
-      },
-    ],
-  },
-  {
-    title: "SQL-level batch insertion",
-    sources: [
-      { suffix: "/config/BatchInsertSettings.java", patterns: [/DEFAULT_BATCH_SIZE/, /configuredBatchSize/] },
-      { suffix: "/config/BatchSqlInjector.java", patterns: [/public class BatchSqlInjector/, /insertBatchSomeColumnInternal/, /FieldFill\.UPDATE/] },
-      { suffix: "/config/DialectInsertBatchSomeColumn.java", patterns: [/public class DialectInsertBatchSomeColumn/, /DbType\.(ORACLE|ORACLE_12C|DM)/] },
-    ],
-  },
-  {
-    title: "Multi-data-source capability boundary",
-    sources: [
-      {
-        suffix: "/MultiDataSourceHolder.java",
-        patterns: [/public class MultiDataSourceHolder/, /Map<String, DataSource>/, /getMultiDataSource\(/],
-      },
-    ],
-  },
-];
-
-const exists = async (target) => {
-  try {
-    await access(target);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-async function walk(root) {
-  if (!await exists(root)) return [];
-  const output = [];
-  for (const item of await readdir(root, { withFileTypes: true })) {
-    const target = path.join(root, item.name);
-    if (item.isDirectory() && !SKIPPED_DIRECTORIES.has(item.name)) output.push(...await walk(target));
-    else if (item.isFile()) output.push(target);
-  }
-  return output;
-}
-
-function relative(root, target) {
-  const value = path.relative(root, target).replaceAll(path.sep, "/");
-  return value && !value.startsWith("..") ? value : target;
-}
-
-function runGit(root, args) {
-  return execFileSync("git", ["-C", root, ...args], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-  }).trim();
-}
-
-export function sourceState(root, componentPaths) {
-  try {
-    const commit = runGit(root, ["rev-parse", "HEAD"]);
-    const componentWorktree = runGit(root, ["status", "--porcelain", "--", ...componentPaths]) ? "dirty" : "clean";
-    const componentTrees = componentPaths.map((componentPath) => {
-      let tree = "missing";
-      try {
-        tree = runGit(root, ["rev-parse", `HEAD:${componentPath}`]);
-      } catch {
-        // The path can be newly added or absent in the indexed commit.
-      }
-      return { path: componentPath, tree };
-    });
-    return { commit, componentWorktree, componentTrees };
-  } catch {
-    return {
-      commit: "unavailable",
-      componentWorktree: "unknown",
-      componentTrees: componentPaths.map((componentPath) => ({ path: componentPath, tree: "unavailable" })),
-    };
-  }
-}
-
-async function sourceRoot() {
-  if (process.env.YSS_SOURCE_ROOT) {
-    const root = path.resolve(process.env.YSS_SOURCE_ROOT);
-    if (await exists(path.join(root, "yss-microservice-components"))) return root;
-    throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`);
-  }
-
-  const home = os.homedir();
-  const candidates = [
-    process.cwd(),
-    ...ancestors(process.cwd()),
-    path.join(home, "Documents/yss-project/yss-cloud-microservice"),
-    path.join(home, "Documents/yss-project"),
-    path.join(home, "Projects/yss-cloud-microservice"),
-    path.join(home, "Projects"),
-  ];
-  for (const base of [path.join(home, "Projects"), path.join(home, "Documents"), path.join(home, "Documents/yss-project")]) {
-    if (!await exists(base)) continue;
-    for (const entry of await readdir(base, { withFileTypes: true })) {
-      if (entry.isDirectory()) candidates.push(path.join(base, entry.name));
-    }
-  }
-  for (const root of candidates) {
-    if (await exists(path.join(root, "yss-microservice-components"))) return path.resolve(root);
-  }
-  throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.");
-}
-
-function ancestors(start) {
-  const output = [];
-  let current = path.resolve(start);
-  while (path.dirname(current) !== current) {
-    current = path.dirname(current);
-    output.push(current);
-  }
-  return output;
-}
-
-async function files(bases) {
-  const output = { docs: [], poms: [], java: [], metadata: [] };
-  for (const base of bases) {
-    for (const target of await walk(base)) {
-      if (DOCS.has(path.basename(target))) output.docs.push(target);
-      else if (path.basename(target) === "pom.xml") output.poms.push(target);
-      else if (target.endsWith(".java") && target.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`)) output.java.push(target);
-      else if (path.basename(target) === "spring.factories") output.metadata.push(target);
-    }
-  }
-  for (const items of Object.values(output)) items.sort();
-  return output;
-}
-
-async function sha256(target) {
-  return createHash("sha256").update(await readFile(target)).digest("hex");
-}
-
-function list(items, render, empty) {
-  return items.length ? items.map(render) : [empty];
-}
-
-async function genericJavaEntries(source, javaFiles) {
-  const selected = javaFiles
-    .filter((target) => KEYS.some((key) => path.basename(target, ".java").includes(key)))
-    .slice(0, 120);
-  const output = [];
-  for (const target of selected) {
-    output.push(`- \`${relative(source, target)}\` — \`sha256:${await sha256(target)}\``);
-  }
-  return output.length ? output : ["- No key Java entry points matched the configured name patterns."];
-}
-
-function matchingLines(contents, patterns) {
-  return contents
-    .split(/\r?\n/)
-    .map((line, index) => ({ line: index + 1, text: line.trim().replace(/\s+/g, " ") }))
-    .filter(({ text }) => text && patterns.some((pattern) => pattern.test(text)))
-    .slice(0, 14);
-}
-
-async function mybatisCapabilityMatrix(source, javaFiles, metadataFiles) {
-  const output = ["## Capability Matrix", ""];
-  for (const capability of MYBATIS_CAPABILITIES) {
-    output.push(`### ${capability.title}`, "");
-    for (const expected of capability.sources) {
-      const target = javaFiles.find((candidate) => relative(source, candidate).endsWith(expected.suffix));
-      if (!target) {
-        output.push(`- \`${path.basename(expected.suffix)}\` — source not found.`);
-        continue;
-      }
-      const sourcePath = relative(source, target);
-      output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
-      const lines = matchingLines(await readFile(target, "utf8"), expected.patterns);
-      if (!lines.length) output.push("  - No configured public fact matched; refresh rules may need maintenance.");
-      else for (const fact of lines) output.push(`  - \`${sourcePath}:${fact.line}\` — \`${fact.text.replaceAll("`", "'")}\``);
-    }
-    output.push("");
-  }
-
-  output.push("### Auto-configuration registration", "");
-  for (const target of metadataFiles) {
-    const sourcePath = relative(source, target);
-    output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
-    const registrations = (await readFile(target, "utf8"))
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .filter((line) => line && !line.startsWith("#"));
-    for (const registration of registrations.slice(0, 12)) output.push(`  - \`${registration.replaceAll("`", "'")}\``);
-  }
-  if (!metadataFiles.length) output.push("- No `spring.factories` registration found.");
-  output.push("");
-  return output;
-}
-
-async function backendIndex({ skill, parts, source, found, now, stateResolver }) {
-  const currentState = stateResolver(source, parts);
-  const bases = parts.map((item) => path.join(source, item));
-  const baseHints = await Promise.all(bases.map(async (target) =>
-    `- \`${relative(source, target)}\` (${await exists(target) ? "existed" : "missing"} when indexed)`,
-  ));
-  const treeLines = currentState.componentTrees.map(({ path: componentPath, tree }) =>
-    `Component tree \`${componentPath}\`: \`${tree}\``,
-  );
-  const lines = [
-    `# ${skill} Source Index`,
-    "",
-    `Generated: ${now}`,
-    `Source commit: \`${currentState.commit}\``,
-    `Component worktree: \`${currentState.componentWorktree}\``,
-    ...treeLines,
-    "Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.",
-    "",
-    "This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.",
-    "",
-    "Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.",
-    "",
-    "## Component Path Hints",
-    "",
-    ...baseHints,
-    "",
-    "## Documentation Files",
-    "",
-    ...list(found.docs, (target) => `- \`${relative(source, target)}\``, "- No component documentation files found."),
-    "",
-    "Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.",
-    "",
-    "## Maven Modules",
-    "",
-    ...list(found.poms, (target) => `- \`${relative(source, path.dirname(target))}\``, "- No Maven modules found."),
-    "",
-  ];
-
-  if (skill === "yss-mybatis") lines.push(...await mybatisCapabilityMatrix(source, found.java, found.metadata));
-  else lines.push("## Key Java Entry Points", "", ...await genericJavaEntries(source, found.java), "");
-
-  lines.push(
-    "## Freshness and Use",
-    "",
-    "- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.",
-    "- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.",
-    "- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.",
-    "- Read only the source entries needed for the current decision or troubleshooting path.",
-    "",
-  );
-  return lines.join("\n");
-}
-
-export async function refresh({
-  skillsRoot,
-  source,
-  now = new Date().toISOString(),
-  frontend = true,
-  backendSkills = Object.keys(BACKEND),
-  stateResolver = sourceState,
-}) {
-  const unknownSkills = backendSkills.filter((skill) => !(skill in BACKEND));
-  if (unknownSkills.length) throw new Error(`Unknown backend source-index skill: ${unknownSkills.join(", ")}`);
-  for (const skill of backendSkills) {
-    const parts = BACKEND[skill];
-    const bases = parts.map((item) => path.join(source, item));
-    const found = await files(bases);
-    const target = path.join(skillsRoot, skill, "references", "source-index.md");
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, await backendIndex({ skill, parts, source, found, now, stateResolver }), "utf8");
-  }
-
-  if (frontend) {
-    for (const [skill, keys] of Object.entries(FRONTEND)) {
-      if (!await exists(path.join(skillsRoot, skill))) continue;
-      const target = path.join(skillsRoot, skill, "references", "frontend-docs.md");
-      await mkdir(path.dirname(target), { recursive: true });
-      await writeFile(target, [
-        `# ${skill} Frontend Documentation`,
-        "",
-        `Generated: ${now}`,
-        "",
-        "Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.",
-        "",
-        ...keys.map((key) => `- ${key}: ${URLS[key]}`),
-        "",
-        "When documentation and local code differ, inspect the current project code before editing and prefer established local usage.",
-        "",
-      ].join("\n"), "utf8");
-    }
-  }
-  return { backend: backendSkills.length, frontend: frontend ? Object.keys(FRONTEND).length : 0 };
-}
-
-async function main() {
-  try {
-    const script = path.dirname(fileURLToPath(import.meta.url));
-    const result = await refresh({
-      skillsRoot: path.resolve(process.env.YSS_SKILLS_ROOT || path.join(script, "../..")),
-      source: await sourceRoot(),
-      frontend: !["0", "false", "no"].includes((process.env.YSS_REFRESH_FRONTEND || "true").toLowerCase()),
-      backendSkills: process.env.YSS_REFRESH_BACKEND_SKILLS
-        ? process.env.YSS_REFRESH_BACKEND_SKILLS.split(",").map((skill) => skill.trim()).filter(Boolean)
-        : Object.keys(BACKEND),
-    });
-    console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`);
-  } catch (error) {
-    console.error(error.message);
-    process.exitCode = 1;
-  }
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.trae/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs

@@ -1,93 +0,0 @@
-import assert from "node:assert/strict";
-import { execFileSync } from "node:child_process";
-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 { refresh, sourceState } from "./refresh-yss-skill-index.mjs";
-
-test("writes Node-labelled generated indexes", async () => {
-  const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
-  await mkdir(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo"),{recursive:true}); await writeFile(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo/CacheConfiguration.java"),"class CacheConfiguration {}");
-  for(const name of ["yss-cache","yss-ui"])await mkdir(path.join(skills,name),{recursive:true});
-  await refresh({skillsRoot:skills,source,now:"2026-01-01T00:00:00Z"});
-  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
-  assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
-});
-
-test("writes a source-backed MyBatis capability matrix without absolute paths", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-mybatis-index-"));
-  const source = path.join(root, "source");
-  const skills = path.join(root, "skills");
-  const component = "yss-microservice-components/yss-component-persistence";
-  const plusJava = path.join(source, component, "yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis");
-  const baseJava = path.join(source, component, "yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis");
-  const commonJava = path.join(source, component, "yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis");
-
-  await mkdir(path.join(plusJava, "support"), { recursive: true });
-  await mkdir(path.join(baseJava, "config"), { recursive: true });
-  await mkdir(commonJava, { recursive: true });
-  await mkdir(path.join(skills, "yss-mybatis"), { recursive: true });
-  await writeFile(path.join(source, component, "pom.xml"), "<project/>");
-  await writeFile(path.join(plusJava, "support/BasePlusRepository.java"), [
-    "public interface BasePlusRepository<T> extends BaseMapper<T> {",
-    "  default Integer insertBatchSomeColumn(List<T> entities) { return 0; }",
-    "  Integer insertBatchSomeColumnInternal(List<T> entities);",
-    "}",
-  ].join("\n"));
-  await writeFile(path.join(baseJava, "config/PageQueryEntityConfigration.java"), [
-    "public class PageQueryEntityConfigration {",
-    "  @ConditionalOnProperty(name = \"yss.mybatis.page-helper.enabled\", havingValue = \"true\", matchIfMissing = true)",
-    "}",
-  ].join("\n"));
-  await writeFile(path.join(commonJava, "MultiDataSourceHolder.java"), [
-    "public class MultiDataSourceHolder {",
-    "  private Map<String, DataSource> multiDataSource;",
-    "}",
-  ].join("\n"));
-
-  await refresh({
-    skillsRoot: skills,
-    source,
-    now: "2026-01-01T00:00:00Z",
-    frontend: false,
-    backendSkills: ["yss-mybatis"],
-    stateResolver: () => ({
-      commit: "a".repeat(40),
-      componentWorktree: "clean",
-      componentTrees: [{ path: component, tree: "b".repeat(40) }],
-    }),
-  });
-
-  const index = await readFile(path.join(skills, "yss-mybatis/references/source-index.md"), "utf8");
-  assert.match(index, /## Capability Matrix/);
-  assert.match(index, /BasePlusRepository<T>/);
-  assert.match(index, /yss\.mybatis\.page-helper\.enabled/);
-  assert.match(index, /Map<String, DataSource>/);
-  assert.match(index, /Component worktree: `clean`/);
-  assert.match(index, /Component tree.*b{40}/);
-  assert.doesNotMatch(index, new RegExp(root.replaceAll("/", "\\/")));
-  assert.doesNotMatch(index, /## Key Java Entry Points/);
-});
-
-test("source freshness is scoped to the indexed component subtree", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-component-state-"));
-  const component = "yss-microservice-components/yss-component-persistence";
-  const componentFile = path.join(root, component, "pom.xml");
-  const unrelatedFile = path.join(root, "yss-microservice-components/other/README.md");
-  await mkdir(path.dirname(componentFile), { recursive: true });
-  await mkdir(path.dirname(unrelatedFile), { recursive: true });
-  await writeFile(componentFile, "<project/>\n");
-  await writeFile(unrelatedFile, "clean\n");
-  execFileSync("git", ["init", "-q"], { cwd: root });
-  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: root });
-  execFileSync("git", ["config", "user.name", "Test"], { cwd: root });
-  execFileSync("git", ["add", "."], { cwd: root });
-  execFileSync("git", ["commit", "-qm", "fixture"], { cwd: root });
-
-  await writeFile(unrelatedFile, "dirty elsewhere\n");
-  assert.equal(sourceState(root, [component]).componentWorktree, "clean");
-
-  await writeFile(componentFile, "<project><dirty/></project>\n");
-  assert.equal(sourceState(root, [component]).componentWorktree, "dirty");
-});