create-yss-spec 3.1.0 → 3.2.0

package/src/template/lifecycle-runtime.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { applyOwnershipToOperations } = require("./ownership-runtime");
+const {
+  validateCustomizationPolicy,
+  resolveCustomizationStrategy,
+  validateGeneratorPolicy,
+  resolveGenerator,
+} = require("./lifecycle-policy");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "../..");
+const MANIFEST_PATH = path.join(PACKAGE_ROOT, "template.manifest.json");
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
+
+const CUSTOMIZATION_POLICY = validateCustomizationPolicy(
+  manifest.customizationPolicy || {
+    version: 1,
+    defaultStrategy: "replace-with-force",
+    rules: [],
+  },
+);
+const GENERATOR_POLICY = validateGeneratorPolicy(
+  manifest.generatorPolicy || { version: 1, rules: [] },
+);
+
+function applyLifecycleToOperations(operations = []) {
+  return applyOwnershipToOperations(operations).map((operation) => {
+    if (operation.ownership === "managed-customizable") {
+      return {
+        ...operation,
+        mergeStrategy:
+          operation.mergeStrategy ||
+          resolveCustomizationStrategy(
+            operation.relativePath,
+            CUSTOMIZATION_POLICY,
+          ),
+      };
+    }
+
+    if (operation.ownership === "generated") {
+      const generator = resolveGenerator(operation.relativePath, GENERATOR_POLICY);
+      return generator
+        ? {
+            ...operation,
+            generatorId: operation.generatorId || generator.generatorId,
+            generatorVersion:
+              operation.generatorVersion || generator.generatorVersion,
+          }
+        : operation;
+    }
+
+    return operation;
+  });
+}
+
+function decoratePlanWithLifecycle(plan, desiredOperations = []) {
+  const operations = applyLifecycleToOperations(desiredOperations);
+  const byPath = new Map(
+    operations.map((operation) => [operation.relativePath, operation]),
+  );
+
+  const decorate = (item) => {
+    const operation = byPath.get(item.path);
+    if (!operation) return item;
+    const result = { ...item };
+    if (operation.mergeStrategy) result.mergeStrategy = operation.mergeStrategy;
+    if (operation.generatorId) result.generatorId = operation.generatorId;
+    if (operation.generatorVersion) {
+      result.generatorVersion = operation.generatorVersion;
+    }
+    return result;
+  };
+
+  return {
+    ...plan,
+    changes: (plan.changes || []).map(decorate),
+    conflicts: (plan.conflicts || []).map(decorate),
+    unsafe: (plan.unsafe || []).map(decorate),
+  };
+}
+
+module.exports = {
+  CUSTOMIZATION_POLICY,
+  GENERATOR_POLICY,
+  applyLifecycleToOperations,
+  decoratePlanWithLifecycle,
+};

package/src/template/migration-planner.js

@@ -0,0 +1,95 @@
+"use strict";
+
+function createMigrationPlan(targetDir) {
+  return {
+    targetDir,
+    operations: [],
+    legacy: [],
+    conflicts: [],
+    unsafe: [],
+  };
+}
+
+function isBlockedMigration(plan) {
+  return Boolean(
+    plan &&
+      ((Array.isArray(plan.conflicts) && plan.conflicts.length > 0) ||
+        (Array.isArray(plan.unsafe) && plan.unsafe.length > 0)),
+  );
+}
+
+function addUnsafe(plan, path, reason) {
+  plan.unsafe.push({ path, reason });
+  return plan;
+}
+
+function addConflict(plan, from, to, reason) {
+  plan.conflicts.push({ from, to, reason });
+  plan.legacy.push({ action: "conflict", from, to, reason });
+  return plan;
+}
+
+function addMove(plan, from, to, reason) {
+  plan.operations.push({ kind: "move", from, to, reason });
+  plan.legacy.push({ action: "move", from, to, reason });
+  return plan;
+}
+
+function addRemove(plan, path, reason, metadata = {}) {
+  plan.operations.push({ kind: "remove", path, reason });
+  plan.legacy.push({
+    action: metadata.action || "remove",
+    from: path,
+    to: metadata.to ?? null,
+    reason,
+  });
+  return plan;
+}
+
+function addReplaceWithTemplate(plan, from, to, reason) {
+  plan.operations.push({ kind: "remove", path: from, reason });
+  plan.legacy.push({
+    action: "replace-with-template",
+    from,
+    to,
+    reason,
+  });
+  return plan;
+}
+
+function addRemoveDuplicate(plan, from, to, reason) {
+  plan.operations.push({
+    kind: "remove",
+    path: from,
+    reason: `${reason}（新旧内容一致）`,
+  });
+  plan.legacy.push({
+    action: "remove-duplicate",
+    from,
+    to,
+    reason,
+  });
+  return plan;
+}
+
+function summarizeMigrationPlan(plan) {
+  return {
+    operations: plan?.operations?.length || 0,
+    legacy: plan?.legacy?.length || 0,
+    conflicts: plan?.conflicts?.length || 0,
+    unsafe: plan?.unsafe?.length || 0,
+    blocked: isBlockedMigration(plan),
+  };
+}
+
+module.exports = {
+  createMigrationPlan,
+  isBlockedMigration,
+  addUnsafe,
+  addConflict,
+  addMove,
+  addRemove,
+  addReplaceWithTemplate,
+  addRemoveDuplicate,
+  summarizeMigrationPlan,
+};

package/src/template/migration-runtime.js

@@ -0,0 +1,247 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+const { treeHash } = require("../template-hash");
+const { targetPath, pathKind } = require("../filesystem/path-utils");
+const {
+  createMigrationPlan,
+  addUnsafe,
+  addConflict,
+  addMove,
+  addRemove,
+  addReplaceWithTemplate,
+  addRemoveDuplicate,
+} = require("./migration-planner");
+
+const AGENT_SKILL_ROOTS = [
+  ".agents/skills",
+  ".claude/skills",
+  ".codex/skills",
+  ".cursor/skills",
+  ".pi/skills",
+  ".qoder/skills",
+  ".trae/skills",
+];
+
+const LEGACY_SKILL_MAPPINGS = [
+  ["to-prd", "to-spec"],
+  ["to-issues", "to-tickets"],
+];
+
+const LEGACY_FILE_MAPPINGS = [
+  ["docs/templates/prd-template.md", "docs/templates/spec-template.md"],
+  [
+    "docs/templates/vertical-slice-issue-template.md",
+    "docs/templates/vertical-slice-ticket-template.md",
+  ],
+];
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function pathContentHash(absolutePath) {
+  const kind = pathKind(absolutePath);
+  if (kind === "file") return sha256(fs.readFileSync(absolutePath));
+  if (kind === "directory") return treeHash(absolutePath);
+  if (kind === "missing") return null;
+  return sha256(`${kind}:${fs.realpathSync(absolutePath)}`);
+}
+
+function pathsEqual(leftPath, rightPath) {
+  const leftKind = pathKind(leftPath);
+  const rightKind = pathKind(rightPath);
+  return (
+    leftKind === rightKind &&
+    leftKind !== "missing" &&
+    pathContentHash(leftPath) === pathContentHash(rightPath)
+  );
+}
+
+function managedPathPrefix(relativePath, desiredPathSet) {
+  return (
+    desiredPathSet.has(relativePath) ||
+    [...desiredPathSet].some((candidate) => candidate.startsWith(`${relativePath}/`))
+  );
+}
+
+function addMigrationDestination(from, to, reason, desiredPathSet, plan) {
+  const source = targetPath(plan.targetDir, from);
+  const destination = targetPath(plan.targetDir, to);
+  const sourceKind = pathKind(source);
+  const destinationKind = pathKind(destination);
+
+  if (sourceKind === "missing") return;
+
+  if ([sourceKind, destinationKind].includes("other")) {
+    addUnsafe(
+      plan,
+      from,
+      `${reason}：源或目标路径是符号链接或其他不可安全判断的类型`,
+    );
+    return;
+  }
+
+  if (managedPathPrefix(to, desiredPathSet)) {
+    addReplaceWithTemplate(plan, from, to, reason);
+    return;
+  }
+
+  if (destinationKind === "missing") {
+    addMove(plan, from, to, reason);
+    return;
+  }
+
+  if (pathsEqual(source, destination)) {
+    addRemoveDuplicate(plan, from, to, reason);
+    return;
+  }
+
+  addConflict(plan, from, to, `${reason}：迁移目标已存在且内容不一致`);
+}
+
+function addDirectoryMigration(from, to, reason, desiredPathSet, plan) {
+  const source = targetPath(plan.targetDir, from);
+  const destination = targetPath(plan.targetDir, to);
+  const sourceKind = pathKind(source);
+  const destinationKind = pathKind(destination);
+
+  if (sourceKind === "missing") return;
+
+  if (sourceKind !== "directory" || destinationKind === "other") {
+    addUnsafe(plan, from, `${reason}：源或目标路径不是可安全遍历的目录`);
+    return;
+  }
+
+  if (destinationKind === "file") {
+    addConflict(plan, from, to, `${reason}：迁移目标是文件而不是目录`);
+    return;
+  }
+
+  const entries = fs.readdirSync(source).filter((entry) => entry !== ".DS_Store");
+  if (entries.length === 0) {
+    addRemove(plan, from, reason, { action: "remove-empty", to });
+    return;
+  }
+
+  for (const entry of entries) {
+    const childFrom = `${from}/${entry}`;
+    const childTo = `${to}/${entry}`;
+    if (pathKind(targetPath(plan.targetDir, childFrom)) === "directory") {
+      addDirectoryMigration(childFrom, childTo, reason, desiredPathSet, plan);
+    } else {
+      addMigrationDestination(childFrom, childTo, reason, desiredPathSet, plan);
+    }
+  }
+
+  addRemove(plan, from, reason, { action: "remove-migrated-directory", to });
+}
+
+function buildLegacyMigrationPlan(
+  targetDir,
+  desiredOperations,
+  { checkFlatTickets = true } = {},
+) {
+  const desiredPathSet = new Set(
+    desiredOperations.map((operation) => operation.relativePath),
+  );
+  const plan = createMigrationPlan(targetDir);
+
+  for (const [oldName, newName] of LEGACY_SKILL_MAPPINGS) {
+    for (const agentRoot of AGENT_SKILL_ROOTS) {
+      addMigrationDestination(
+        `${agentRoot}/${oldName}`,
+        `${agentRoot}/${newName}`,
+        `旧 skill ${oldName} 迁移为 ${newName}`,
+        desiredPathSet,
+        plan,
+      );
+    }
+  }
+
+  for (const [oldPath, newPath] of LEGACY_FILE_MAPPINGS) {
+    addMigrationDestination(
+      oldPath,
+      newPath,
+      "旧模板路径迁移",
+      desiredPathSet,
+      plan,
+    );
+  }
+
+  addDirectoryMigration(
+    "docs/requirements/issues",
+    "docs/requirements/tickets",
+    "旧 Ticket 目录迁移",
+    desiredPathSet,
+    plan,
+  );
+
+  const requirementsPath = targetPath(targetDir, "docs/requirements");
+  if (pathKind(requirementsPath) === "directory") {
+    for (const entry of fs.readdirSync(requirementsPath, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith("-prd.md")) {
+        const oldPath = `docs/requirements/${entry.name}`;
+        const newPath = `docs/requirements/${entry.name.replace(/-prd\.md$/, "-spec.md")}`;
+        addMigrationDestination(
+          oldPath,
+          newPath,
+          "旧规格文件名迁移",
+          desiredPathSet,
+          plan,
+        );
+      }
+    }
+  }
+
+  const legacyScratch = targetPath(targetDir, ".scratch");
+  if (pathKind(legacyScratch) === "directory") {
+    for (const entry of fs.readdirSync(legacyScratch, { withFileTypes: true })) {
+      if (entry.name === ".DS_Store") continue;
+      addMigrationDestination(
+        `.scratch/${entry.name}`,
+        `docs/.scratch/${entry.name}`,
+        "根 scratch 目录迁移",
+        desiredPathSet,
+        plan,
+      );
+    }
+  }
+
+  if (checkFlatTickets) {
+    const legacyDirectory = "docs/requirements/tickets";
+    const directoryPath = targetPath(targetDir, legacyDirectory);
+    if (pathKind(directoryPath) === "directory") {
+      const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+      const unsafeEntries = entries.filter(
+        (entry) => entry.name !== ".gitkeep" && entry.name !== ".DS_Store",
+      );
+
+      if (unsafeEntries.length > 0) {
+        for (const entry of unsafeEntries) {
+          addUnsafe(
+            plan,
+            `${legacyDirectory}/${entry.name}`,
+            "扁平 Ticket 无法可靠推断功能归属，不能自动迁移",
+          );
+        }
+      } else if (!desiredPathSet.has(`${legacyDirectory}/.gitkeep`)) {
+        addRemove(plan, legacyDirectory, "删除空的旧 Ticket 目录", {
+          action: "remove-empty",
+          to: null,
+        });
+      }
+    }
+  }
+
+  return plan;
+}
+
+module.exports = {
+  AGENT_SKILL_ROOTS,
+  LEGACY_SKILL_MAPPINGS,
+  LEGACY_FILE_MAPPINGS,
+  buildLegacyMigrationPlan,
+};

package/src/template/ownership-metadata.js

@@ -0,0 +1,79 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const {
+  OWNERSHIP_POLICY,
+  resolveTemplateOwnership,
+} = require("./ownership-runtime");
+
+function ownershipPolicyHash(policy = OWNERSHIP_POLICY) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(policy))
+    .digest("hex");
+}
+
+function decorateMetadataOwnership(metadata, policy = OWNERSHIP_POLICY) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new TypeError("metadata must be an object");
+  }
+
+  const managedFiles = Object.fromEntries(
+    Object.entries(metadata.managedFiles || {}).map(([relativePath, record]) => [
+      relativePath,
+      {
+        ...record,
+        ownership:
+          record?.ownership || resolveTemplateOwnership(relativePath),
+      },
+    ]),
+  );
+
+  return {
+    ...metadata,
+    ownershipPolicyVersion: policy.version,
+    ownershipPolicyHash: ownershipPolicyHash(policy),
+    managedFiles,
+  };
+}
+
+function ownershipPolicyDrift(metadata, policy = OWNERSHIP_POLICY) {
+  const expectedVersion = policy.version;
+  const expectedHash = ownershipPolicyHash(policy);
+  const actualVersion = metadata?.ownershipPolicyVersion;
+  const actualHash = metadata?.ownershipPolicyHash;
+
+  if (actualVersion === undefined || actualHash === undefined) {
+    return {
+      state: "missing",
+      expectedVersion,
+      expectedHash,
+      actualVersion: actualVersion ?? null,
+      actualHash: actualHash ?? null,
+    };
+  }
+
+  if (actualVersion !== expectedVersion || actualHash !== expectedHash) {
+    return {
+      state: "drift",
+      expectedVersion,
+      expectedHash,
+      actualVersion,
+      actualHash,
+    };
+  }
+
+  return {
+    state: "matched",
+    expectedVersion,
+    expectedHash,
+    actualVersion,
+    actualHash,
+  };
+}
+
+module.exports = {
+  ownershipPolicyHash,
+  decorateMetadataOwnership,
+  ownershipPolicyDrift,
+};

package/src/template/ownership-policy.js

@@ -0,0 +1,149 @@
+"use strict";
+
+const OWNERSHIP_POLICY_VERSION = 1;
+const OWNERSHIP_TYPES = Object.freeze([
+  "managed",
+  "managed-customizable",
+  "generated",
+  "user-owned",
+  "protected",
+]);
+const OWNERSHIP_TYPE_SET = new Set(OWNERSHIP_TYPES);
+
+const DEFAULT_OWNERSHIP_POLICY = Object.freeze({
+  version: OWNERSHIP_POLICY_VERSION,
+  default: "managed",
+  rules: [],
+});
+
+function normalizePolicyPath(value) {
+  return String(value || "")
+    .replaceAll("\\", "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+}
+
+function isOwnershipType(value) {
+  return OWNERSHIP_TYPE_SET.has(value);
+}
+
+function validateOwnershipPattern(pattern) {
+  if (typeof pattern !== "string" || !pattern.trim()) {
+    throw new Error("ownership rule pattern 不能为空");
+  }
+  const normalized = normalizePolicyPath(pattern);
+  if (
+    !normalized ||
+    normalized === "." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../") ||
+    normalized.startsWith("/")
+  ) {
+    throw new Error(`ownership rule pattern 越界：${pattern}`);
+  }
+  if (normalized.includes("**") && !normalized.endsWith("/**")) {
+    throw new Error(`ownership rule 仅支持末尾 /**：${pattern}`);
+  }
+  if (normalized.includes("*") && !normalized.endsWith("/*") && !normalized.endsWith("/**")) {
+    throw new Error(`ownership rule 仅支持 exact、/* 或 /**：${pattern}`);
+  }
+  return normalized;
+}
+
+function validateOwnershipPolicy(policy) {
+  const value = policy || DEFAULT_OWNERSHIP_POLICY;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("ownershipPolicy 必须是 JSON 对象");
+  }
+  if (value.version !== OWNERSHIP_POLICY_VERSION) {
+    throw new Error(`不支持的 ownershipPolicy version：${value.version}`);
+  }
+  if (!isOwnershipType(value.default)) {
+    throw new Error(`ownershipPolicy default 非法：${value.default}`);
+  }
+  if (!Array.isArray(value.rules)) {
+    throw new Error("ownershipPolicy rules 必须是数组");
+  }
+
+  const seen = new Set();
+  const rules = value.rules.map((rule, index) => {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+      throw new Error(`ownershipPolicy rules[${index}] 必须是对象`);
+    }
+    const pattern = validateOwnershipPattern(rule.pattern);
+    if (seen.has(pattern)) {
+      throw new Error(`ownershipPolicy pattern 重复：${pattern}`);
+    }
+    seen.add(pattern);
+    if (!isOwnershipType(rule.ownership)) {
+      throw new Error(
+        `ownershipPolicy rules[${index}].ownership 非法：${rule.ownership}`,
+      );
+    }
+    return { pattern, ownership: rule.ownership };
+  });
+
+  return {
+    version: OWNERSHIP_POLICY_VERSION,
+    default: value.default,
+    rules,
+  };
+}
+
+function matchesOwnershipPattern(relativePath, pattern) {
+  const target = normalizePolicyPath(relativePath);
+  const normalizedPattern = validateOwnershipPattern(pattern);
+
+  if (normalizedPattern.endsWith("/**")) {
+    const prefix = normalizedPattern.slice(0, -3);
+    return target === prefix || target.startsWith(`${prefix}/`);
+  }
+  if (normalizedPattern.endsWith("/*")) {
+    const prefix = normalizedPattern.slice(0, -2);
+    if (!target.startsWith(`${prefix}/`)) return false;
+    return !target.slice(prefix.length + 1).includes("/");
+  }
+  return target === normalizedPattern;
+}
+
+function resolveOwnership(relativePath, policy = DEFAULT_OWNERSHIP_POLICY) {
+  const validated = validateOwnershipPolicy(policy);
+  for (const rule of validated.rules) {
+    if (matchesOwnershipPattern(relativePath, rule.pattern)) {
+      return rule.ownership;
+    }
+  }
+  return validated.default;
+}
+
+function isTemplateManagedOwnership(ownership) {
+  return ["managed", "managed-customizable", "generated"].includes(ownership);
+}
+
+function isWriteProtectedOwnership(ownership) {
+  return ownership === "user-owned" || ownership === "protected";
+}
+
+function ownershipWriteViolation(operation) {
+  const ownership = operation?.ownership || "managed";
+  if (!isWriteProtectedOwnership(ownership)) return null;
+  const path = operation?.relativePath || operation?.path || "unknown";
+  return ownership === "protected"
+    ? `${path} 被 ownership policy 标记为 protected，CLI 不得写入或覆盖`
+    : `${path} 被 ownership policy 标记为 user-owned，不属于受管模板文件`;
+}
+
+module.exports = {
+  OWNERSHIP_POLICY_VERSION,
+  OWNERSHIP_TYPES,
+  DEFAULT_OWNERSHIP_POLICY,
+  normalizePolicyPath,
+  isOwnershipType,
+  validateOwnershipPattern,
+  validateOwnershipPolicy,
+  matchesOwnershipPattern,
+  resolveOwnership,
+  isTemplateManagedOwnership,
+  isWriteProtectedOwnership,
+  ownershipWriteViolation,
+};