create-yss-spec 3.4.9 → 3.5.0

package/README.md

@@ -2,11 +2,11 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.4.9`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
+源码候选版本：`3.5.0`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
 
 ## 本版模板能力
 
-本版同步 Handoff v5、领域与阶段决策、前后端交付边界和 committed-source 身份校验。CLI 仍会在同一事务内刷新生成型 `skills-lock.json`，再运行项目实例校验；刷新或校验失败恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
+本版新增按阶段分发项目实例资产及 `assets ensure` 命令；旧实例沿用原有分发范围。CLI 在同一事务内刷新生成型 `skills-lock.json` 并运行项目实例校验，失败时恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
 ## 快速开始
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.4.9",
+  "version": "3.5.0",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/api/_sync-service.js

@@ -2,12 +2,13 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { isDeepStrictEqual } = require("node:util");
 
 const { pathKind, targetPath, normalizeRelativePath } = require("../filesystem/path-utils");
 const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
 const { runInTransaction } = require("../filesystem/transaction-runner");
 const { assertBundledFamily, assertTargetFamily } = require("../family-runtime");
-const { gitDirtyWarning } = require("../git/worktree");
+const { collectGitRoots, gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildSyncPlanFromRuntime } = require("../template/sync-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
@@ -15,6 +16,7 @@ const { classifyRemovedFiles } = require("../template/prune-planner");
 const { decorateMetadataOwnership } = require("../template/ownership-metadata");
 const { decorateMetadataLifecycle } = require("../template/lifecycle-metadata");
 const {
+  readProjectSkillLock,
   refreshGeneratedProjectInstance,
   verifyGeneratedProjectInstance,
 } = require("../template/verification-runtime");
@@ -47,7 +49,7 @@ function isInsideTemplateRoot(targetDir) {
   );
 }
 
-function inspectExistingTargetDir(targetDir, { force = false } = {}) {
+function inspectExistingTargetDir(targetDir, { force = false, gitRoots = null } = {}) {
   if (isInsideTemplateRoot(targetDir)) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
@@ -57,6 +59,7 @@ function inspectExistingTargetDir(targetDir, { force = false } = {}) {
   assertTargetWorkingTreeWritable(targetDir, {
     force,
     packageRoot: PACKAGE_ROOT,
+    ...(gitRoots && { deps: { collectGitRoots: () => gitRoots } }),
   });
 }
 
@@ -75,7 +78,9 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
   assertBundledFamily(snapshot);
   const resolvedTargetDir = normalizeTargetDir(targetDir, cwd);
   assertTargetFamily(resolvedTargetDir);
-  inspectExistingTargetDir(resolvedTargetDir, { force: Boolean(force) });
+  const gitRoots = collectGitRoots(resolvedTargetDir);
+  const securityOptions = { packageRoot: PACKAGE_ROOT, deps: { collectGitRoots: () => gitRoots } };
+  inspectExistingTargetDir(resolvedTargetDir, { force: Boolean(force), gitRoots });
 
   const { metadata } = loadTemplateMetadata(resolvedTargetDir);
   const identity = readTargetIdentity(resolvedTargetDir);
@@ -83,6 +88,7 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     resolvedTargetDir,
     metadata,
     identity,
+    snapshot,
   );
   const migrationPlan = buildLegacyMigrationPlan(
     resolvedTargetDir,
@@ -99,9 +105,7 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     warning,
     toVersion: PACKAGE_MANIFEST.version,
     getUnmanagedReason: (operation) =>
-      operation.unsafeReason || unmanagedPathReason(resolvedTargetDir, operation.relativePath, {
-        packageRoot: PACKAGE_ROOT,
-      }),
+      operation.unsafeReason || unmanagedPathReason(resolvedTargetDir, operation.relativePath, securityOptions),
     getPathKind: (operation) => pathKind(operation.targetPath),
     getFileHash: (operation) => fileHash(operation.targetPath),
   });
@@ -111,7 +115,7 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     getPathKind: (relativePath) => pathKind(targetPath(resolvedTargetDir, relativePath)),
     getFileHash: (relativePath) => fileHash(targetPath(resolvedTargetDir, relativePath)),
     getUnmanagedReason: (relativePath) =>
-      unmanagedPathReason(resolvedTargetDir, relativePath, { packageRoot: PACKAGE_ROOT }),
+      unmanagedPathReason(resolvedTargetDir, relativePath, securityOptions),
   });
   const readmeOwnershipTransferred = syncPlan.removed.includes("README.md");
   syncPlan.removed = syncPlan.removed.filter((relativePath) => relativePath !== "README.md");
@@ -133,6 +137,7 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
 
   return {
     targetDir: resolvedTargetDir,
+    snapshot,
     metadata,
     identity,
     desiredOperations,
@@ -158,27 +163,109 @@ function assertSyncApplicable(context) {
   }
 }
 
+function isVerifiedNoopCandidate(context) {
+  const { metadata, migrationPlan, syncPlan } = context;
+  if (
+    syncPlan.updated.some((operation) => operation.relativePath !== "skills-lock.json") ||
+    syncPlan.added.length > 0 ||
+    syncPlan.skipped.length > 0 ||
+    syncPlan.removed.length > 0 ||
+    syncPlan.prunable.length > 0 ||
+    syncPlan.retainedRemoved.length > 0 ||
+    syncPlan.readmeOwnershipTransferred ||
+    (syncPlan.alreadyMissing || []).length > 0 ||
+    migrationPlan.operations.length > 0
+  ) return false;
+
+  const nextMetadata = decorateMetadataLifecycle(
+    decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan, {
+      snapshot: context.snapshot,
+      currentHashes: syncPlan.currentHashes,
+    })),
+  );
+  return isDeepStrictEqual(
+    { ...nextMetadata, lastSyncedAt: metadata.lastSyncedAt },
+    metadata,
+  );
+}
+
 function applySyncContext(context, { force = false, prune = false } = {}) {
   assertSyncApplicable(context);
-  const { targetDir, metadata, migrationPlan, syncPlan } = context;
+  const { targetDir, metadata, desiredOperations, migrationPlan, syncPlan } = context;
+  if (isVerifiedNoopCandidate(context)) {
+    try {
+      verifyGeneratedProjectInstance(targetDir);
+      return {
+        schemaVersion: APPLY_RESULT_SCHEMA_VERSION,
+        operation: "sync",
+        targetDir,
+        backupPath: null,
+        template: context.plan.template,
+        stats: { updated: 0, added: 0, skipped: 0, removed: 0, forceApplied: 0, pruned: 0 },
+        skipped: [],
+        removed: [],
+        prunable: [],
+        pruned: [],
+        retainedRemoved: [],
+        ownershipTransferred: [],
+      };
+    } catch {
+      // A stale generated lock needs the normal transactional refresh and verification.
+    }
+  }
+  const previousSkillLock = readProjectSkillLock(targetDir);
   const managedToApply = [
     ...syncPlan.updated,
     ...syncPlan.added,
     ...(force ? syncPlan.forceableConflicts : []),
   ];
   syncPlan.pruned = prune ? [...syncPlan.prunable] : [];
+  const affectedPaths = [
+    ...affectedPathsForManagedOperations(managedToApply),
+    ...affectedPathsForMigration(migrationPlan),
+    ...syncPlan.pruned,
+    "skills-lock.json",
+    TEMPLATE_METADATA_FILENAME,
+  ];
 
   const { backupPath } = runInTransaction({
     targetDir,
     operation: "sync",
-    affectedPaths: [
-      ...affectedPathsForManagedOperations(managedToApply),
-      ...affectedPathsForMigration(migrationPlan),
-      ...syncPlan.pruned,
-      "skills-lock.json",
-      TEMPLATE_METADATA_FILENAME,
-    ],
+    affectedPaths,
     execute: (transaction) => {
+      const gitRoots = collectGitRoots(targetDir);
+      const securityOptions = { packageRoot: PACKAGE_ROOT, deps: { collectGitRoots: () => gitRoots } };
+      assertTargetWorkingTreeWritable(targetDir, { ...securityOptions, force });
+      for (const relativePath of new Set(affectedPaths)) {
+        const reason = unmanagedPathReason(targetDir, relativePath, securityOptions);
+        if (reason) throw new Error(`${relativePath}: ${reason}`);
+        const kind = pathKind(targetPath(targetDir, relativePath));
+        if (kind === "other") throw new Error(`${relativePath}: 写入前路径类型已变化为 ${kind}`);
+        if (["skills-lock.json", TEMPLATE_METADATA_FILENAME].includes(relativePath) && kind === "directory") {
+          throw new Error(`${relativePath}: 写入前路径类型已变化为 ${kind}`);
+        }
+      }
+      if (!isDeepStrictEqual(loadTemplateMetadata(targetDir).metadata, metadata)) {
+        throw new Error("模板元数据在规划后已变化，请重新运行 sync");
+      }
+      for (const operation of managedToApply) {
+        const kind = pathKind(targetPath(targetDir, operation.relativePath));
+        const plannedHash = syncPlan.currentHashes[operation.relativePath];
+        if (plannedHash === undefined ? kind !== "missing" : kind !== "file" || fileHash(operation.targetPath) !== plannedHash) {
+          throw new Error(`${operation.relativePath}: 规划后目标文件已变化，请重新运行 sync`);
+        }
+      }
+      for (const relativePath of syncPlan.pruned) {
+        const current = targetPath(targetDir, relativePath);
+        if (pathKind(current) !== "file" || fileHash(current) !== metadata.managedFiles[relativePath]?.contentHash) {
+          throw new Error(`${relativePath}: 待清理文件在规划后已变化，请重新运行 sync`);
+        }
+      }
+      const currentMigration = buildLegacyMigrationPlan(targetDir, desiredOperations, { checkFlatTickets: false });
+      if (!isDeepStrictEqual(currentMigration.operations, migrationPlan.operations) ||
+          currentMigration.unsafe.length || currentMigration.conflicts.length) {
+        throw new Error("旧路径迁移在规划后已变化，请重新运行 sync");
+      }
       for (const operation of managedToApply) {
         applyManagedOperation(operation, transaction);
       }
@@ -187,12 +274,18 @@ function applySyncContext(context, { force = false, prune = false } = {}) {
         transaction.remove(targetPath(targetDir, relativePath));
       }
       verifyGeneratedSyncInstance(targetDir);
-      refreshGeneratedProjectInstance(targetDir);
+      refreshGeneratedProjectInstance(targetDir, {
+        previousSkillLock,
+        previousManagedFiles: metadata.managedFiles,
+        transaction,
+      });
       verifyGeneratedProjectInstance(targetDir);
       const nextMetadata = decorateMetadataLifecycle(
-        decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan)),
+        decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan, { snapshot: context.snapshot })),
       );
-      writeTemplateMetadata(targetDir, nextMetadata, transaction);
+      if (!isDeepStrictEqual({ ...nextMetadata, lastSyncedAt: metadata.lastSyncedAt }, metadata)) {
+        writeTemplateMetadata(targetDir, nextMetadata, transaction);
+      }
     },
   });
 

package/src/cli/args.js

@@ -8,6 +8,7 @@ const VALUE_OPTIONS = new Map([
   ["--team-size", "teamSize"],
   ["--target-dir", "targetDir"],
   ["--issue-tracker", "issueTracker"],
+  ["--agent-runtime", "agentRuntime"],
 ]);
 
 function parseArgs(argv = []) {

package/src/cli/help.js

@@ -16,6 +16,8 @@ COMMANDS
   sync       同步已有模板实例的受管资产
   diff       只计算同步差异，不写入文件
   doctor     检查模板实例、身份、Git 和安全状态
+  skills     按需补装 Skill 或增加 Agent 平台
+  assets     按生命周期阶段补装所需文件与 Skill
   update     检查 npm 最新版本，如有更新则安装
   upgrade    update 的别名
 
@@ -25,6 +27,7 @@ OPTIONS
   --team-size <size>                 团队规模；init 不传则可留空，默认「待补充」
   --target-dir <dir>                 目标目录；init 不传则进入交互输入，sync/diff/doctor 默认为当前目录
   --issue-tracker github|gitlab      默认 issue tracker 偏好（默认 github）
+  --agent-runtime codex|cursor|pi    init/attach 必选；交互模式可在提示中选择
   --dry-run                          兼容预演模式，不写入文件
   --plan                             sync：输出结构化文本计划，不写入文件
   --json                             sync/diff/doctor：输出机器可读 JSON，不写入文件
@@ -34,7 +37,7 @@ OPTIONS
                                      update：即使已是最新时仍重新安装；npx / 源码目录仍不覆盖
   --prune                            sync：备份并删除与旧受管基线一致的退出分发文件
   --git-init                         初始化完成后执行 git init
-  --include-example-docs             显式保留示例文档（默认开启）
+  --include-example-docs             显式保留示例文档（默认关闭）
   --no-example-docs                  不生成示例文档
   -h, --help                         显示本帮助信息
   -v, --version                      显示 CLI 版本
@@ -70,6 +73,12 @@ EXAMPLES
   $ npx create-yss-spec@latest doctor --json
   $ npx create-yss-spec@latest sync --target-dir . --force
   $ npx create-yss-spec@latest sync --plan --prune
+  $ npx create-yss-spec@latest skills ensure yss-web-controller --plan
+  $ npx create-yss-spec@latest assets ensure stage.spec-architecture --plan
+  $ npx create-yss-spec@latest assets ensure stage.spec-architecture --apply
+  $ npx create-yss-spec@latest skills ensure yss-web-controller --apply
+  $ npx create-yss-spec@latest skills runtime add cursor --plan
+  $ npx create-yss-spec@latest skills runtime add cursor --apply
   $ npx create-yss-spec@latest sync --prune
   $ npx create-yss-spec update
   $ npx create-yss-spec update --dry-run

package/src/cli/index.js

@@ -29,6 +29,7 @@ const { runDiff } = require("../commands/diff");
 const { runDoctor } = require("../commands/doctor");
 const { runInit } = require("../commands/init");
 const { runSync } = require("../commands/sync");
+const { runSkills, runAssets } = require("../commands/skills");
 const { runUpdateCommand } = require("../commands/update");
 const { printHelp, printVersion } = require("./help");
 const { resolveCommand } = require("./router");
@@ -58,6 +59,8 @@ async function runCli(argv = []) {
   if (route.command === "sync") {
     return runSync(route.args);
   }
+  if (route.command === "skills") return runSkills(route.args);
+  if (route.command === "assets") return runAssets(route.args);
   if (route.command === "doctor") {
     return runDoctor(route.args);
   }

package/src/cli/prompts.js

@@ -11,8 +11,9 @@ function normalizeInteractiveOptions(options, values) {
     gitInit: Boolean(options.gitInit),
     includeExampleDocs:
       options.includeExampleDocs === undefined
-        ? true
+        ? false
         : Boolean(options.includeExampleDocs),
+    ...(values.agentRuntime || options.agentRuntime ? { agentRuntime: values.agentRuntime || options.agentRuntime } : {}),
   };
 }
 
@@ -40,12 +41,14 @@ async function promptForMissingOptions(options, deps = {}) {
         : await rl.question("团队规模（可留空）: ");
     const targetDir =
       options.targetDir || (await rl.question("目标目录: ")).trim();
+    const agentRuntime = options.agentRuntime || (await rl.question("Agent 平台（codex/cursor/pi）: ")).trim();
 
     return normalizeInteractiveOptions(options, {
       projectName,
       businessDomain,
       teamSize: (teamSizeInput || "").trim() || "待补充",
       targetDir,
+      agentRuntime,
     });
   } finally {
     rl.close();
@@ -53,6 +56,7 @@ async function promptForMissingOptions(options, deps = {}) {
 }
 
 async function promptFromBufferedInput(options, deps = {}) {
+  if (!options.agentRuntime) throw new Error("无交互 init 必须显式指定 --agent-runtime codex|cursor|pi");
   const stdin = deps.stdin || process.stdin;
   const stdout = deps.stdout || process.stdout;
   const chunks = [];

package/src/cli/router.js

@@ -19,6 +19,8 @@ function resolveCommand(argv = []) {
   if (head === "sync") {
     return { command: "sync", args: rest };
   }
+  if (head === "skills") return { command: "skills", args: rest };
+  if (head === "assets") return { command: "assets", args: rest };
   if (head === "attach") {
     return { command: "attach", args: rest };
   }

package/src/commands/attach.js

@@ -4,6 +4,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const { parseArgs } = require("../cli/args");
+const { assertRuntime } = require("../template/distribution-runtime");
 const { pathKind, targetPath, normalizeRelativePath } = require("../filesystem/path-utils");
 const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
 const { runInTransaction } = require("../filesystem/transaction-runner");
@@ -29,6 +30,8 @@ const {
 } = require("../template/verification-runtime");
 
 function assertRequiredOptions(options) {
+  if (!options.agentRuntime && !process.stdin.isTTY) throw new Error("无交互 attach 必须显式指定 --agent-runtime codex|cursor|pi");
+  if (options.agentRuntime) assertRuntime(options.agentRuntime);
   if (!options.projectName) {
     throw new Error("attach 需要 --project-name，项目名称不能为空");
   }
@@ -73,8 +76,9 @@ function attachVariables(options) {
     issueTracker: options.issueTracker || "github",
     includeExampleDocs:
       options.includeExampleDocs === undefined
-        ? true
+        ? false
         : Boolean(options.includeExampleDocs),
+    agentRuntime: options.agentRuntime,
   };
 }
 
@@ -156,8 +160,14 @@ function affectedPathsForMigration(migrationPlan) {
   );
 }
 
-function runAttach(argv = []) {
+async function runAttach(argv = []) {
   const options = parseArgs(argv);
+  if (!options.agentRuntime && process.stdin.isTTY) {
+    const readline = require("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try { options.agentRuntime = (await rl.question("Agent 平台（codex/cursor/pi）: ")).trim(); }
+    finally { rl.close(); }
+  }
   if (options.prune) throw new Error("--prune 仅适用于 sync");
   assertRequiredOptions(options);
 

package/src/commands/init.js

@@ -4,6 +4,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const { parseArgs } = require("../cli/args");
+const { assertRuntime } = require("../template/distribution-runtime");
 const { promptForMissingOptions } = require("../cli/prompts");
 const { printHelp, printVersion } = require("../cli/help");
 const { pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
@@ -32,6 +33,7 @@ const {
 } = require("../template/verification-runtime");
 
 function assertRequiredOptions(options) {
+  assertRuntime(options.agentRuntime);
   if (!options.projectName) {
     throw new Error("init 需要 --project-name，项目名称不能为空");
   }