create-yss-spec 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # create-yss-spec
 
-用于初始化 `yss-spec-project-template` 模板实例仓库的 npm CLI。
+用于初始化和同步 `yss-spec-project-template` 模板实例仓库的 npm CLI。
 
 ## 用法
 
@@ -24,6 +24,30 @@ npx create-yss-spec@latest
 - `--issue-tracker github|gitlab`
 - `--include-example-docs`
 - `--no-example-docs`
+- `sync` 子命令
+- 基于 `.yss-template.json` 的模板版本基线
+- 已有模板实例仓库的受管模板资产同步
+
+## 同步已有模板实例仓库
+
+当项目仓库已经由 `create-yss-spec` 初始化，并且根目录存在 `.yss-template.json` 时，可以执行：
+
+```bash
+npx create-yss-spec@latest sync
+```
+
+只预演，不真实写入：
+
+```bash
+npx create-yss-spec@latest sync --dry-run
+```
+
+当前同步能力的边界：
+
+- 只支持带模板元数据的模板实例仓库
+- 默认只更新未被本地修改的受管模板文件
+- 对本地已修改文件只提示和跳过，不自动覆盖
+- 对模板已删除文件只报告，不自动删除
 
 ## 开发验证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Initialize a YSS spec project template repository",
   "files": [
     "bin",

package/src/cli.js

@@ -1,9 +1,13 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const readline = require("node:readline/promises");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const PACKAGE_MANIFEST = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+);
 const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const REPO_TEMPLATE_ROOT = path.resolve(PACKAGE_ROOT, "../..");
 const REPO_MANIFEST_PATH = path.join(REPO_TEMPLATE_ROOT, "template.manifest.json");
@@ -17,18 +21,33 @@ const TEMPLATE_ROOT = IS_REPO_DEVELOPMENT
 const TEMPLATE_MANIFEST_PATH = IS_REPO_DEVELOPMENT
   ? REPO_MANIFEST_PATH
   : BUNDLED_MANIFEST_PATH;
-const TEMPLATE_MANIFEST = JSON.parse(
-  fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8"),
-);
+const TEMPLATE_MANIFEST_TEXT = fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8");
+const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
 const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
 const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
 const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
 const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
+const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
+const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
 const REPO_TRACKED_STATE = IS_REPO_DEVELOPMENT
   ? loadRepoTrackedState(REPO_TEMPLATE_ROOT)
   : null;
 
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function nowIsoString() {
+  return new Date().toISOString();
+}
+
+function getTemplateSource() {
+  return IS_REPO_DEVELOPMENT
+    ? "repo-development"
+    : `npm:${PACKAGE_MANIFEST.name}@${PACKAGE_MANIFEST.version}`;
+}
+
 function loadRepoTrackedState(repoRoot) {
   const result = spawnSync("git", ["ls-files"], {
     cwd: repoRoot,
@@ -259,6 +278,49 @@ function renderTemplateFile(relativePath, content, variables) {
   return content;
 }
 
+function collectManagedFileHashes(operations) {
+  const managedFiles = {};
+
+  for (const operation of operations) {
+    if (operation.type !== "copy" && operation.type !== "render") {
+      continue;
+    }
+
+    managedFiles[operation.relativePath] = {
+      type: operation.type,
+      contentHash: sha256(fs.readFileSync(operation.targetPath)),
+    };
+  }
+
+  return managedFiles;
+}
+
+function writeTemplateMetadata(targetDir, metadata) {
+  const metadataPath = path.join(targetDir, TEMPLATE_METADATA_FILENAME);
+  fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+}
+
+function buildTemplateMetadata(targetDir, variables, operations) {
+  const timestamp = nowIsoString();
+
+  return {
+    templateName: PACKAGE_MANIFEST.name,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: getTemplateSource(),
+    initializedAt: timestamp,
+    lastSyncedAt: timestamp,
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    variables: {
+      projectName: variables.projectName,
+      businessDomain: variables.businessDomain,
+      teamSize: variables.teamSize,
+      issueTracker: variables.issueTracker,
+      includeExampleDocs: variables.includeExampleDocs,
+    },
+    managedFiles: collectManagedFileHashes(operations),
+  };
+}
+
 function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
   const operations = [];
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
@@ -405,7 +467,245 @@ function initializeGitRepository(targetDir) {
   }
 }
 
-async function runCli(argv = []) {
+function loadTemplateMetadata(targetDir) {
+  const metadataPath = path.join(targetDir, TEMPLATE_METADATA_FILENAME);
+
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(
+      `当前目录不是受支持的模板实例仓库，缺少模板元数据文件 ${TEMPLATE_METADATA_FILENAME}`,
+    );
+  }
+
+  return {
+    metadataPath,
+    metadata: JSON.parse(fs.readFileSync(metadataPath, "utf8")),
+  };
+}
+
+function buildSyncVariables(metadata) {
+  const variables = metadata.variables || {};
+
+  return {
+    projectName: variables.projectName,
+    businessDomain: variables.businessDomain,
+    teamSize: variables.teamSize || "待补充",
+    issueTracker: variables.issueTracker || "github",
+    includeExampleDocs:
+      variables.includeExampleDocs === undefined
+        ? true
+        : Boolean(variables.includeExampleDocs),
+  };
+}
+
+function buildDesiredManagedOperations(targetDir, metadata) {
+  const variables = buildSyncVariables(metadata);
+
+  return buildCopyPlan(TEMPLATE_ROOT, targetDir, variables).filter(
+    (operation) => operation.type === "copy" || operation.type === "render",
+  );
+}
+
+function buildDesiredManagedFile(operation, metadata) {
+  const variables = buildSyncVariables(metadata);
+
+  if (operation.type === "render") {
+    const renderedContent = renderTemplateFile(
+      operation.relativePath,
+      fs.readFileSync(operation.sourcePath, "utf8"),
+      variables,
+    );
+
+    return {
+      ...operation,
+      desiredContent: renderedContent,
+      desiredHash: sha256(renderedContent),
+    };
+  }
+
+  return {
+    ...operation,
+    desiredHash: sha256(fs.readFileSync(operation.sourcePath)),
+  };
+}
+
+function classifySyncPlan(targetDir, metadata) {
+  const managedFiles = metadata.managedFiles || {};
+  const desiredOperations = buildDesiredManagedOperations(targetDir, metadata).map(
+    (operation) => buildDesiredManagedFile(operation, metadata),
+  );
+  const desiredPathSet = new Set(
+    desiredOperations.map((operation) => operation.relativePath),
+  );
+
+  const updated = [];
+  const added = [];
+  const unchanged = [];
+  const skipped = [];
+
+  for (const operation of desiredOperations) {
+    const existingRecord = managedFiles[operation.relativePath];
+    const existsOnDisk = fs.existsSync(operation.targetPath);
+
+    if (!existingRecord) {
+      if (!existsOnDisk) {
+        added.push(operation);
+        continue;
+      }
+
+      const currentHash = sha256(fs.readFileSync(operation.targetPath));
+      if (currentHash === operation.desiredHash) {
+        unchanged.push(operation);
+      } else {
+        skipped.push({
+          ...operation,
+          reason: "文件已存在，但不在受管模板文件基线中",
+        });
+      }
+      continue;
+    }
+
+    if (!existsOnDisk) {
+      added.push(operation);
+      continue;
+    }
+
+    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    if (currentHash !== existingRecord.contentHash) {
+      skipped.push({
+        ...operation,
+        reason: "检测到本地已修改的受管文件",
+      });
+      continue;
+    }
+
+    if (currentHash === operation.desiredHash) {
+      unchanged.push(operation);
+      continue;
+    }
+
+    updated.push(operation);
+  }
+
+  const removed = Object.keys(managedFiles).filter(
+    (relativePath) => !desiredPathSet.has(relativePath),
+  );
+
+  return {
+    updated,
+    added,
+    unchanged,
+    skipped,
+    removed,
+    desiredOperations,
+  };
+}
+
+function printSyncDryRun(targetDir, metadata, syncPlan) {
+  console.log("sync dry-run 预览");
+  console.log(`目标目录：${targetDir}`);
+  console.log(
+    `模板版本：${metadata.templateVersion || "unknown"} -> ${PACKAGE_MANIFEST.version}`,
+  );
+
+  for (const operation of syncPlan.updated) {
+    console.log(`update: ${operation.relativePath}`);
+  }
+
+  for (const operation of syncPlan.added) {
+    console.log(`add: ${operation.relativePath}`);
+  }
+
+  for (const operation of syncPlan.skipped) {
+    console.log(`skip: ${operation.relativePath} (${operation.reason})`);
+  }
+
+  for (const relativePath of syncPlan.removed) {
+    console.log(`remove-report: ${relativePath}`);
+  }
+}
+
+function applyManagedFileOperation(operation) {
+  fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+
+  if (operation.type === "render") {
+    fs.writeFileSync(operation.targetPath, operation.desiredContent, "utf8");
+    return;
+  }
+
+  fs.copyFileSync(operation.sourcePath, operation.targetPath);
+}
+
+function syncTemplateInstance(targetDir, metadata, dryRun) {
+  const syncPlan = classifySyncPlan(targetDir, metadata);
+
+  if (dryRun) {
+    printSyncDryRun(targetDir, metadata, syncPlan);
+    return;
+  }
+
+  for (const operation of [...syncPlan.updated, ...syncPlan.added]) {
+    applyManagedFileOperation(operation);
+  }
+
+  const nextManagedFiles = { ...(metadata.managedFiles || {}) };
+  for (const operation of syncPlan.desiredOperations) {
+    if (!fs.existsSync(operation.targetPath)) {
+      continue;
+    }
+
+    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    if (currentHash !== operation.desiredHash) {
+      continue;
+    }
+
+    nextManagedFiles[operation.relativePath] = {
+      type: operation.type,
+      contentHash: operation.desiredHash,
+    };
+  }
+
+  const nextMetadata = {
+    ...metadata,
+    templateName: PACKAGE_MANIFEST.name,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: getTemplateSource(),
+    lastSyncedAt: nowIsoString(),
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    managedFiles: nextManagedFiles,
+  };
+
+  writeTemplateMetadata(targetDir, nextMetadata);
+
+  console.log("同步完成");
+  console.log(
+    `模板版本：${metadata.templateVersion || "unknown"} -> ${PACKAGE_MANIFEST.version}`,
+  );
+  console.log(`自动更新：${syncPlan.updated.length}`);
+  console.log(`新增文件：${syncPlan.added.length}`);
+  console.log(`跳过文件：${syncPlan.skipped.length}`);
+  console.log(`删除差异：${syncPlan.removed.length}`);
+
+  if (syncPlan.skipped.length > 0) {
+    console.log("本地已修改，已跳过：");
+    for (const operation of syncPlan.skipped) {
+      console.log(`- ${operation.relativePath}: ${operation.reason}`);
+    }
+  }
+
+  if (syncPlan.removed.length > 0) {
+    console.log("模板已移除但未自动删除：");
+    for (const relativePath of syncPlan.removed) {
+      console.log(`- ${relativePath}`);
+    }
+  }
+
+  console.log("下一步建议：");
+  console.log("1. 运行 git diff 或 git status 检查同步结果");
+  console.log("2. 人工处理被跳过文件和删除差异（如有）");
+  console.log("3. 确认无误后提交本次模板同步结果");
+}
+
+async function runInit(argv = []) {
   const promptedOptions = await promptForMissingOptions(parseArgs(argv));
   assertRequiredOptions(promptedOptions);
 
@@ -421,6 +721,10 @@ async function runCli(argv = []) {
 
   prepareTargetDir(targetDir, targetState);
   executePlan(operations, promptedOptions);
+  writeTemplateMetadata(
+    targetDir,
+    buildTemplateMetadata(targetDir, promptedOptions, operations),
+  );
 
   if (promptedOptions.gitInit) {
     initializeGitRepository(targetDir);
@@ -438,6 +742,22 @@ async function runCli(argv = []) {
   console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
 }
 
+function runSync(argv = []) {
+  const options = parseArgs(argv);
+  const targetDir = normalizeTargetDir(options.targetDir || ".");
+  const { metadata } = loadTemplateMetadata(targetDir);
+  syncTemplateInstance(targetDir, metadata, Boolean(options.dryRun));
+}
+
+async function runCli(argv = []) {
+  if (argv[0] === "sync") {
+    runSync(argv.slice(1));
+    return;
+  }
+
+  await runInit(argv);
+}
+
 module.exports = {
   runCli,
 };

package/template/CONTEXT.md

@@ -22,5 +22,8 @@
 | 模板源仓库 | 承载 `yss-spec-project-template` 权威模板内容及其演进规则的仓库。 | 不等同于实例化后的具体项目仓库。 |
 | 模板实例仓库 | 由模板初始化后生成、面向某个具体项目使用的仓库。 | 不要与模板源仓库混用。 |
 | 模板初始化 CLI | 用于把模板源仓库实例化为新项目初始仓库的命令行工具。 | 不等同于业务运行时代码脚手架。 |
+| 模板同步 | 将已有模板实例仓库与某个更新后的模板快照进行对齐的过程。 | 不等同于重新初始化；通常要考虑本地改动保留、冲突提示和可回滚性。 |
+| 模板快照版本 | 某次发布时模板内容的可识别版本标识，通常对应 npm 包版本、Git tag 或 commit。 | 需要用于判断实例仓库当前基线和目标同步版本。 |
+| 受管模板文件 | 被 CLI 明确纳入同步策略的文件或目录集合。 | 只有受管文件才应被自动更新、跳过或冲突提示。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/docs/user-guide/create-yss-spec-cli-guide.md

@@ -17,7 +17,8 @@
 - 生成前端 / 后端运行时代码工程
 - 自动安装依赖
 - 自动创建远端 Git 仓库、CI 或 Issue Board
-- 把已有项目升级到最新模板版本
+- 直接接管没有模板元数据的历史老项目
+- 自动解决本地已修改受管文件的冲突
 
 ## 快速开始
 
@@ -78,6 +79,22 @@ npx create-yss-spec@latest \
 
 `--dry-run` 只展示计划，不会创建目录，也不会删除已有文件。
 
+### 同步已有模板实例仓库
+
+```bash
+npx create-yss-spec@latest sync
+```
+
+适合已经由 `create-yss-spec` 初始化过、并且根目录带有 `.yss-template.json` 的模板实例仓库。
+
+### 只预演同步，不真正写入
+
+```bash
+npx create-yss-spec@latest sync --dry-run
+```
+
+适合在升级前先查看版本变化、将要更新的文件、将被跳过的本地改动文件，以及模板已删除但不会自动删除的文件。
+
 ## 参数说明
 
 | 参数 | 含义 | 默认行为 |
@@ -93,6 +110,12 @@ npx create-yss-spec@latest \
 | `--include-example-docs` | 显式保留示例文档 | 默认开启 |
 | `--no-example-docs` | 不生成示例文档 | 默认关闭 |
 
+`sync` 子命令当前只支持：
+
+- 在模板实例仓库根目录执行
+- 仓库内已存在 `.yss-template.json`
+- 以当前 npm 已发布包内置模板快照作为同步源
+
 ## 输出内容说明
 
 CLI 会根据模板清单把源仓库内容分成三类处理：
@@ -114,6 +137,12 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 
 如果启用了 `--git-init`，目标目录下还会生成 `.git/`。
 
+初始化完成后，CLI 还会额外生成：
+
+- `.yss-template.json`
+
+这个文件用于记录模板名称、模板版本、模板来源、最近同步时间、受管模板文件基线和关键渲染变量。后续 `sync` 能否安全工作，依赖这份模板元数据。
+
 ## 默认安全策略
 
 为了避免误覆盖，CLI 采用默认安全策略：
@@ -123,6 +152,13 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 - 目标目录不能位于模板源仓库内部
 - `--dry-run` 没有副作用
 
+对于 `sync`，默认安全策略还包括：
+
+- 当前目录缺少 `.yss-template.json` 时，直接拒绝同步
+- 只自动更新未被本地修改的受管模板文件
+- 本地已修改的受管文件会被跳过并报告
+- 模板新版本已删除的受管文件只报告，不自动删除
+
 ## 示例结果
 
 一次典型执行完成后，你会看到类似输出：
@@ -138,6 +174,25 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 
 如果已经传了 `--git-init`，第二步会提示执行 `git status` 检查初始化结果。
 
+一次典型同步完成后，你会看到类似输出：
+
+```text
+同步完成
+模板版本：0.9.0 -> 1.0.0
+自动更新：2
+新增文件：1
+跳过文件：1
+删除差异：1
+本地已修改，已跳过：
+- README.md: 检测到本地已修改的受管文件
+模板已移除但未自动删除：
+- docs/legacy-note.md
+下一步建议：
+1. 运行 git diff 或 git status 检查同步结果
+2. 人工处理被跳过文件和删除差异（如有）
+3. 确认无误后提交本次模板同步结果
+```
+
 ## 常见问题
 
 ### 1. 提示“目标目录非空，当前主路径不支持覆盖已有内容”
@@ -170,12 +225,32 @@ printf 'Acme Spec Repo\nInvestment Research\n12\n/tmp/acme-spec-repo\n' \
 
 这是设计上的非目标范围。当前 CLI 只负责初始化研发管理模板实例仓库，组织级权限操作和后续 bootstrap 仍由人工控制。
 
+### 5. 为什么 `sync` 提示缺少模板元数据
+
+说明当前目录不是受支持的模板实例仓库，或者它是一个早期初始化的历史项目，还没有 `.yss-template.json` 基线。
+
+处理方式：
+
+- 先确认当前目录是否真的是由 `create-yss-spec` 初始化出来的项目
+- 当前版本的 `sync` 只支持带模板元数据的项目
+- 历史老项目的接管 / attach 不在本版范围内
+
+### 6. 为什么 `sync` 没有覆盖我改过的文件
+
+这是刻意的默认安全策略。CLI 会把这类文件识别为“本地已修改的受管文件”，只报告、跳过，不自动覆盖。
+
+处理方式：
+
+- 查看输出中的跳过文件列表
+- 用 `git diff` 比较当前项目版本和模板版本的差异
+- 人工决定是否合并模板变更
+
 ## 维护与验证
 
 如果你在维护这个 CLI，本地验证命令是：
 
 ```bash
-npm test
+node --test packages/create-yss-spec/tests/init-cli.test.js
 ```
 
 发布前可检查打包内容：

package/template.manifest.json

@@ -22,13 +22,18 @@
     ".codex/skills/.DS_Store",
     ".pi/settings.json",
     "docs/discovery/yss-spec-cli-init-discovery.md",
+    "docs/discovery/yss-spec-cli-template-sync-discovery.md",
     "docs/implementation/yss-spec-cli-init-build-checklist.md",
     "docs/implementation/yss-spec-cli-init-routing.md",
     "docs/requirements/issues/yss-spec-cli-init-slice-01-main-path.md",
     "docs/requirements/issues/yss-spec-cli-init-slice-02-safety-controls.md",
     "docs/requirements/issues/yss-spec-cli-init-slice-03-template-manifest.md",
     "docs/requirements/issues/yss-spec-cli-init-slice-04-delivery-verification.md",
+    "docs/requirements/issues/yss-spec-cli-template-sync-slice-01-main-path.md",
+    "docs/requirements/issues/yss-spec-cli-template-sync-slice-02-safety-controls.md",
+    "docs/requirements/issues/yss-spec-cli-template-sync-slice-03-delivery-verification.md",
     "docs/requirements/yss-spec-cli-init-prd.md",
+    "docs/requirements/yss-spec-cli-template-sync-prd.md",
     "scripts/sync-cli-template.js"
   ],
   "renderPaths": [