create-yss-spec 3.1.0 → 3.2.0

package/src/template/ownership-runtime.js

@@ -0,0 +1,109 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const {
+  DEFAULT_OWNERSHIP_POLICY,
+  validateOwnershipPolicy,
+  resolveOwnership,
+  ownershipWriteViolation,
+  isTemplateManagedOwnership,
+} = require("./ownership-policy");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "../..");
+const MANIFEST_PATH = path.join(PACKAGE_ROOT, "template.manifest.json");
+
+function loadOwnershipPolicy() {
+  const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
+  return validateOwnershipPolicy(
+    manifest.ownershipPolicy || DEFAULT_OWNERSHIP_POLICY,
+  );
+}
+
+const OWNERSHIP_POLICY = loadOwnershipPolicy();
+
+function resolveTemplateOwnership(relativePath) {
+  return resolveOwnership(relativePath, OWNERSHIP_POLICY);
+}
+
+function applyOwnershipToOperations(operations = []) {
+  return operations.map((operation) => ({
+    ...operation,
+    ownership:
+      operation.ownership || resolveTemplateOwnership(operation.relativePath),
+  }));
+}
+
+function ownershipAwareUnmanagedReason(operation, fallback = null) {
+  const violation = ownershipWriteViolation(operation);
+  if (violation) return violation;
+  return typeof fallback === "function" ? fallback(operation) : null;
+}
+
+function assertWritableTemplateOperations(operations = []) {
+  for (const operation of applyOwnershipToOperations(operations)) {
+    const violation = ownershipWriteViolation(operation);
+    if (violation) throw new Error(violation);
+  }
+}
+
+function decoratePlanWithOwnership(plan, desiredOperations = []) {
+  const operations = applyOwnershipToOperations(desiredOperations);
+  const ownershipByPath = new Map(
+    operations.map((operation) => [operation.relativePath, operation.ownership]),
+  );
+  const ownershipFor = (item) =>
+    ownershipByPath.get(item.path) || resolveTemplateOwnership(item.path);
+
+  return {
+    ...plan,
+    changes: (plan.changes || []).map((item) => ({
+      ...item,
+      ownership: item.ownership || ownershipFor(item),
+    })),
+    conflicts: (plan.conflicts || []).map((item) => ({
+      ...item,
+      ownership: item.ownership || ownershipFor(item),
+    })),
+    unsafe: (plan.unsafe || []).map((item) => ({
+      ...item,
+      ownership: item.ownership || ownershipFor(item),
+    })),
+  };
+}
+
+function summarizeOwnership(operations = []) {
+  const summary = Object.fromEntries(
+    [
+      "managed",
+      "managed-customizable",
+      "generated",
+      "user-owned",
+      "protected",
+    ].map((name) => [name, 0]),
+  );
+  for (const operation of applyOwnershipToOperations(operations)) {
+    summary[operation.ownership] += 1;
+  }
+  return summary;
+}
+
+function templateManagedOperations(operations = []) {
+  return applyOwnershipToOperations(operations).filter((operation) =>
+    isTemplateManagedOwnership(operation.ownership),
+  );
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  OWNERSHIP_POLICY,
+  loadOwnershipPolicy,
+  resolveTemplateOwnership,
+  applyOwnershipToOperations,
+  ownershipAwareUnmanagedReason,
+  assertWritableTemplateOperations,
+  decoratePlanWithOwnership,
+  summarizeOwnership,
+  templateManagedOperations,
+};

package/src/template/plan-schema.js

@@ -0,0 +1,36 @@
+"use strict";
+
+const PLAN_SCHEMA_VERSION = 1;
+
+function normalizePlan(plan) {
+  if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+    throw new TypeError("plan must be an object");
+  }
+  if (!plan.operation) {
+    throw new TypeError("plan.operation is required");
+  }
+
+  return {
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    operation: plan.operation,
+    targetDir: plan.targetDir || null,
+    template: plan.template || null,
+    changes: Array.isArray(plan.changes) ? plan.changes : [],
+    conflicts: Array.isArray(plan.conflicts) ? plan.conflicts : [],
+    unsafe: Array.isArray(plan.unsafe) ? plan.unsafe : [],
+    warnings: Array.isArray(plan.warnings) ? plan.warnings : [],
+    blocked: Boolean(plan.blocked),
+    stats: plan.stats && typeof plan.stats === "object" ? plan.stats : {},
+    migration: plan.migration || null,
+  };
+}
+
+function serializePlan(plan, space = 2) {
+  return `${JSON.stringify(normalizePlan(plan), null, space)}\n`;
+}
+
+module.exports = {
+  PLAN_SCHEMA_VERSION,
+  normalizePlan,
+  serializePlan,
+};

package/src/template/sync-planner-runtime.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const {
+  classifySyncOperations,
+  createSyncPlan,
+} = require("./sync-planner");
+const {
+  ownershipAwareUnmanagedReason,
+  decoratePlanWithOwnership,
+} = require("./ownership-runtime");
+const {
+  applyLifecycleToOperations,
+  decoratePlanWithLifecycle,
+} = require("./lifecycle-runtime");
+
+function buildSyncPlanFromRuntime({
+  targetDir,
+  metadata,
+  desiredOperations,
+  migration,
+  warning = null,
+  toVersion = "unknown",
+  getUnmanagedReason,
+  getPathKind,
+  getFileHash,
+}) {
+  const managedFiles = metadata?.managedFiles || {};
+  const lifecycleOperations = applyLifecycleToOperations(desiredOperations);
+  const classified = classifySyncOperations({
+    managedFiles,
+    desiredOperations: lifecycleOperations,
+    getUnmanagedReason: (operation) =>
+      ownershipAwareUnmanagedReason(operation, getUnmanagedReason),
+    getPathKind,
+    getFileHash,
+  });
+
+  const basePlan = createSyncPlan({
+    targetDir,
+    fromVersion: metadata?.templateVersion || metadata?.cliVersion || "unknown",
+    toVersion,
+    classified,
+    migration,
+    warnings: warning ? [warning] : [],
+  });
+  const ownershipPlan = decoratePlanWithOwnership(basePlan, lifecycleOperations);
+  const plan = decoratePlanWithLifecycle(ownershipPlan, lifecycleOperations);
+
+  return {
+    classified,
+    plan,
+  };
+}
+
+module.exports = {
+  buildSyncPlanFromRuntime,
+};

package/src/template/sync-planner.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const { normalizePlan } = require("./plan-schema");
+
+function classifySyncOperations({
+  managedFiles = {},
+  desiredOperations = [],
+  getUnmanagedReason = () => null,
+  getPathKind,
+  getFileHash,
+}) {
+  if (typeof getPathKind !== "function") {
+    throw new TypeError("classifySyncOperations requires getPathKind");
+  }
+  if (typeof getFileHash !== "function") {
+    throw new TypeError("classifySyncOperations requires getFileHash");
+  }
+
+  const updated = [];
+  const added = [];
+  const unchanged = [];
+  const skipped = [];
+  const conflicts = [];
+  const forceableConflicts = [];
+  const unsafe = [];
+
+  for (const operation of desiredOperations) {
+    const unmanagedReason = getUnmanagedReason(operation);
+    if (unmanagedReason) {
+      unsafe.push({ ...operation, reason: unmanagedReason });
+      continue;
+    }
+
+    const existingRecord = managedFiles[operation.relativePath];
+    const existingKind = getPathKind(operation);
+
+    if (existingKind === "missing") {
+      added.push(operation);
+      continue;
+    }
+
+    if (existingKind !== "file") {
+      unsafe.push({
+        ...operation,
+        reason: `目标路径类型为 ${existingKind}，无法安全判断是否可以替换`,
+      });
+      continue;
+    }
+
+    const currentHash = getFileHash(operation);
+
+    if (operation.identityConversion && currentHash === operation.identitySourceHash) {
+      updated.push(operation);
+      continue;
+    }
+
+    if (!existingRecord) {
+      if (currentHash === operation.desiredHash) {
+        unchanged.push(operation);
+      } else {
+        const conflict = {
+          ...operation,
+          reason: "文件已存在，但不在受管模板文件基线中",
+        };
+        conflicts.push(conflict);
+        skipped.push(conflict);
+      }
+      continue;
+    }
+
+    if (currentHash === operation.desiredHash) {
+      unchanged.push(operation);
+      continue;
+    }
+
+    if (currentHash !== existingRecord.contentHash) {
+      const conflict = {
+        ...operation,
+        reason:
+          operation.mergeStrategy === "manual"
+            ? "检测到本地已修改的可定制文件；mergeStrategy=manual，必须人工处理"
+            : "检测到本地已修改的受管文件",
+      };
+      conflicts.push(conflict);
+      if (operation.mergeStrategy !== "manual") {
+        forceableConflicts.push(conflict);
+      }
+      skipped.push(conflict);
+      continue;
+    }
+
+    updated.push(operation);
+  }
+
+  const desiredPathSet = new Set(desiredOperations.map((operation) => operation.relativePath));
+  const removed = Object.keys(managedFiles).filter(
+    (relativePath) => !desiredPathSet.has(relativePath),
+  );
+
+  return {
+    updated,
+    added,
+    unchanged,
+    skipped,
+    conflicts,
+    forceableConflicts,
+    unsafe,
+    removed,
+    desiredOperations,
+  };
+}
+
+function createSyncPlan({
+  targetDir,
+  fromVersion = "unknown",
+  toVersion = "unknown",
+  classified,
+  migration = null,
+  warnings = [],
+}) {
+  if (!classified || typeof classified !== "object") {
+    throw new TypeError("createSyncPlan requires classified sync operations");
+  }
+
+  const migrationConflicts = migration?.conflicts || [];
+  const migrationUnsafe = migration?.unsafe || [];
+  const blocked =
+    classified.unsafe.length > 0 ||
+    migrationConflicts.length > 0 ||
+    migrationUnsafe.length > 0;
+
+  const changes = [
+    ...classified.updated.map((operation) => ({
+      action: "update",
+      path: operation.relativePath,
+    })),
+    ...classified.added.map((operation) => ({
+      action: "add",
+      path: operation.relativePath,
+    })),
+    ...classified.removed.map((relativePath) => ({
+      action: "remove-report",
+      path: relativePath,
+    })),
+  ];
+
+  const classifiedConflicts = classified.conflicts.map((operation) => ({
+    path: operation.relativePath,
+    reason: operation.reason,
+    forceable: classified.forceableConflicts.includes(operation),
+    source: "managed-file",
+  }));
+  const normalizedMigrationConflicts = migrationConflicts.map((item) => ({
+    path: item.from || item.path || item.to,
+    from: item.from,
+    to: item.to,
+    reason: item.reason,
+    forceable: false,
+    source: "migration",
+  }));
+
+  return normalizePlan({
+    operation: "sync",
+    targetDir,
+    template: {
+      from: fromVersion,
+      to: toVersion,
+    },
+    changes,
+    conflicts: [...classifiedConflicts, ...normalizedMigrationConflicts],
+    unsafe: [
+      ...classified.unsafe.map((operation) => ({
+        path: operation.relativePath,
+        reason: operation.reason,
+        source: "managed-file",
+      })),
+      ...migrationUnsafe.map((item) => ({
+        path: item.path,
+        reason: item.reason,
+        source: "migration",
+      })),
+    ],
+    migration: migration || {
+      operations: [],
+      legacy: [],
+      conflicts: [],
+      unsafe: [],
+    },
+    warnings,
+    blocked,
+    stats: {
+      updated: classified.updated.length,
+      added: classified.added.length,
+      unchanged: classified.unchanged.length,
+      skipped: classified.skipped.length,
+      conflicts: classified.conflicts.length + migrationConflicts.length,
+      unsafe: classified.unsafe.length + migrationUnsafe.length,
+      removed: classified.removed.length,
+    },
+  });
+}
+
+module.exports = {
+  classifySyncOperations,
+  createSyncPlan,
+};

package/src/template/verification-runtime.js

@@ -0,0 +1,154 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const { targetPath, pathKind } = require("../filesystem/path-utils");
+const {
+  TEMPLATE_MANIFEST,
+  readTargetIdentity,
+} = require("./instance-runtime");
+
+const INSTANCE_FORBIDDEN_PATHS = [
+  ".template-source",
+  ".github",
+  ".cursor/environment.json",
+  "wiki",
+  "docs/reviews",
+];
+
+function verificationEnvironment(environment = process.env) {
+  const sanitized = { ...environment };
+  for (const key of Object.keys(sanitized)) {
+    if (key === "NODE_TEST_CONTEXT" || key.startsWith("NODE_TEST_")) {
+      delete sanitized[key];
+    }
+  }
+  return sanitized;
+}
+
+function initializeGitRepository(targetDir) {
+  const result = spawnSync("git", ["init"], {
+    cwd: targetDir,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "git init 执行失败");
+  }
+}
+
+function runTemplateVerification(targetDir, scriptPath, args = ["--check"]) {
+  const commandPath = targetPath(targetDir, scriptPath);
+  const result = spawnSync(commandPath, args, {
+    cwd: targetDir,
+    encoding: "utf8",
+    env: verificationEnvironment(),
+  });
+  const output = [result.stdout, result.stderr].filter(Boolean).join("");
+  if (output) {
+    process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+  }
+  if (result.status !== 0) {
+    const detail = result.error?.message || output.trim();
+    throw new Error(
+      `生成项目校验失败：${scriptPath}${detail ? `\n${detail}` : ""}`,
+    );
+  }
+}
+
+function runTemplateVerificationWithGit(targetDir, scriptPath, args = []) {
+  const gitPath = targetPath(targetDir, ".git");
+  const probe = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: targetDir,
+    encoding: "utf8",
+  });
+  if (probe.status === 0 && probe.stdout.trim() === "true") {
+    runTemplateVerification(targetDir, scriptPath, args);
+    return;
+  }
+
+  let backupRoot;
+  let backupGitPath;
+  try {
+    try {
+      fs.lstatSync(gitPath);
+      backupRoot = fs.mkdtempSync(
+        path.join(os.tmpdir(), "create-yss-spec-git-backup-"),
+      );
+      backupGitPath = path.join(backupRoot, ".git");
+      fs.renameSync(gitPath, backupGitPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+
+    initializeGitRepository(targetDir);
+    runTemplateVerification(targetDir, scriptPath, args);
+  } finally {
+    fs.rmSync(gitPath, { recursive: true, force: true });
+    if (backupGitPath) fs.renameSync(backupGitPath, gitPath);
+    if (backupRoot) fs.rmSync(backupRoot, { recursive: true, force: true });
+  }
+}
+
+function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = false } = {}) {
+  if (checkForbiddenPaths) {
+    const forbiddenPaths = [
+      ...INSTANCE_FORBIDDEN_PATHS,
+      ...(TEMPLATE_MANIFEST.initExcludeRootEntries || []),
+      ...(TEMPLATE_MANIFEST.initExcludeRootFiles || []),
+      ...(TEMPLATE_MANIFEST.initExcludePaths || []),
+    ];
+    for (const relativePath of [...new Set(forbiddenPaths)]) {
+      if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
+        throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+      }
+    }
+  }
+
+  const identity = readTargetIdentity(targetDir);
+  if (
+    identity.state !== "valid" ||
+    identity.fields.repository_mode !== "project-instance"
+  ) {
+    throw new Error("初始化结果的 yss-project.yaml 必须是 project-instance");
+  }
+
+  const agentsContent = fs.readFileSync(targetPath(targetDir, "AGENTS.md"), "utf8");
+  const readmeContent = fs.readFileSync(targetPath(targetDir, "README.md"), "utf8");
+  if (agentsContent.includes("[填写]") || readmeContent.includes("[填写]")) {
+    throw new Error("初始化结果仍包含模板占位信息");
+  }
+}
+
+function verifyGeneratedInit(targetDir) {
+  verifyGeneratedInstance(targetDir, { checkForbiddenPaths: true });
+}
+
+function verifyGeneratedAttach(targetDir) {
+  runTemplateVerification(targetDir, "scripts/sync-skills");
+  runTemplateVerification(targetDir, "scripts/update-skill-lock");
+  // Attach validates the generated project instance, not the template source
+  // release candidate. The release profile intentionally runs source-governance
+  // checks (including external tooling such as ripgrep) that are inappropriate
+  // as a runtime dependency for end-user projects. Use the fast profile with a
+  // known routed instance path so required files, repository identity and
+  // read-only Git invariants are still checked without escalating to release.
+  runTemplateVerificationWithGit(targetDir, "scripts/run-template-verification", [
+    "--profile",
+    "fast",
+    "--changed-file",
+    "README.md",
+  ]);
+}
+
+module.exports = {
+  verificationEnvironment,
+  initializeGitRepository,
+  runTemplateVerification,
+  runTemplateVerificationWithGit,
+  verifyGeneratedInstance,
+  verifyGeneratedInit,
+  verifyGeneratedAttach,
+};

package/src/validation/identity.js

@@ -0,0 +1,41 @@
+"use strict";
+
+function parseRepositoryIdentity(content) {
+  const fields = {};
+  for (const [index, line] of String(content).split(/\r?\n/).entries()) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = line.match(/^([a-z_][a-z0-9_-]*):\s*([^\s#]+)\s*$/);
+    if (!match) throw new Error(`yss-project.yaml 第 ${index + 1} 行格式非法`);
+    const [, key, value] = match;
+    if (fields[key] !== undefined) throw new Error(`yss-project.yaml 不允许重复字段：${key}`);
+    fields[key] = value;
+  }
+
+  const keys = Object.keys(fields).sort();
+  if (keys.join(",") !== "repository_mode,schema_version") {
+    throw new Error("yss-project.yaml 只能包含 schema_version 和 repository_mode");
+  }
+  if (fields.schema_version !== "1") {
+    throw new Error("yss-project.yaml 的 schema_version 必须为 1");
+  }
+  if (!["template-source", "project-instance"].includes(fields.repository_mode)) {
+    throw new Error("yss-project.yaml 的 repository_mode 必须是 template-source 或 project-instance");
+  }
+  return fields;
+}
+
+function convertTemplateSourceToInstance(content) {
+  const identity = parseRepositoryIdentity(content);
+  if (identity.repository_mode !== "template-source") {
+    throw new Error("模板 yss-project.yaml 必须声明 repository_mode: template-source");
+  }
+  const rendered = String(content).replace(/^repository_mode:\s*template-source$/m, "repository_mode: project-instance");
+  const converted = parseRepositoryIdentity(rendered);
+  if (converted.repository_mode !== "project-instance") {
+    throw new Error("生成项目 yss-project.yaml 未转换为 project-instance");
+  }
+  return rendered;
+}
+
+module.exports = { parseRepositoryIdentity, convertTemplateSourceToInstance };