create-yss-spec 3.1.0 → 3.2.0

package/src/family-identity.js

@@ -0,0 +1,365 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const FAMILIES = [
+  {
+    name: "create-yss-spec",
+    metadata: ".yss-template.json",
+    template: "yss-spec-project-template",
+    profile: null,
+  },
+  {
+    name: "create-yss-harness-design",
+    metadata: ".yss-harness-design.json",
+    template: "yss-harness-design-agent",
+    profile: "harness.business-ddd-strategy-handoff",
+  },
+  {
+    name: "create-yss-harness-dev",
+    metadata: ".yss-harness-dev.json",
+    template: "yss-harness-dev-agent",
+    profile: "harness.dev-agent-slice",
+  },
+  {
+    name: "create-yss-harness-backend",
+    metadata: ".yss-harness-backend.json",
+    template: "yss-harness-backend-agent",
+    profile: "harness.backend-delivery",
+  },
+  {
+    name: "create-yss-harness-frontend",
+    metadata: ".yss-harness-frontend.json",
+    template: "yss-harness-frontend-agent",
+    profile: "harness.frontend-delivery",
+  },
+];
+
+const PROFILE_PATH = "docs/process/harness-profile.yaml";
+
+function statOrMissing(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function readIdentityFile(root, relative) {
+  let current = root;
+  const parts = relative.split("/");
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    const stat = statOrMissing(current);
+    if (!stat) return null;
+    if (
+      stat.isSymbolicLink() ||
+      (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())
+    ) {
+      throw new Error(`身份路径不能是符号链接或特殊文件：${relative}`);
+    }
+  }
+  return fs.readFileSync(current, "utf8");
+}
+
+function topLevelJsonKeys(text) {
+  const keys = [];
+  let depth = 0;
+  let index = 0;
+
+  while (index < text.length) {
+    const char = text[index];
+    if (char === "{") {
+      depth += 1;
+      index += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      index += 1;
+      continue;
+    }
+    if (char !== '"') {
+      index += 1;
+      continue;
+    }
+
+    const start = index;
+    index += 1;
+    let escaped = false;
+    while (index < text.length) {
+      const current = text[index];
+      if (escaped) {
+        escaped = false;
+      } else if (current === "\\") {
+        escaped = true;
+      } else if (current === '"') {
+        break;
+      }
+      index += 1;
+    }
+    if (index >= text.length) break;
+
+    const literal = text.slice(start, index + 1);
+    index += 1;
+    let cursor = index;
+    while (/\s/.test(text[cursor] || "")) cursor += 1;
+    if (depth === 1 && text[cursor] === ":") {
+      keys.push(JSON.parse(literal));
+    }
+  }
+
+  return keys;
+}
+
+function parseJsonObject(text, relative) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`身份文件格式非法 ${relative}：${error.message}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`身份文件格式非法 ${relative}：必须是对象`);
+  }
+
+  const seen = new Set();
+  for (const key of topLevelJsonKeys(text)) {
+    if (seen.has(key)) {
+      throw new Error(`身份文件格式非法 ${relative}：重复字段 ${key}`);
+    }
+    seen.add(key);
+  }
+  return value;
+}
+
+function stripYamlComment(line) {
+  let single = false;
+  let double = false;
+  let escaped = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if (double && escaped) {
+      escaped = false;
+      continue;
+    }
+    if (double && char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (!double && char === "'") single = !single;
+    else if (!single && char === '"') double = !double;
+    else if (!single && !double && char === "#") return line.slice(0, index);
+  }
+  return line;
+}
+
+function parseYamlScalar(raw, relative, lineNumber) {
+  const value = raw.trim();
+  if (!value) return undefined;
+
+  if (value.startsWith("'") || value.startsWith('"')) {
+    const quote = value[0];
+    if (!value.endsWith(quote) || value.length < 2) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行字符串未闭合`);
+    }
+    if (quote === "'") {
+      return value.slice(1, -1).replaceAll("''", "'");
+    }
+    try {
+      return JSON.parse(value);
+    } catch (error) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行 ${error.message}`);
+    }
+  }
+
+  if (/^[+-]?\d+$/.test(value)) return Number(value);
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null" || value === "~") return null;
+  if (/^[\[\]{}|>&*!]/.test(value)) {
+    throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行不支持复杂 YAML 值`);
+  }
+  return value;
+}
+
+function parseProfileYaml(text, relative = PROFILE_PATH) {
+  const root = {};
+  const rootKeys = new Set();
+  const nestedKeys = new Set();
+  let section = null;
+
+  for (const [offset, rawLine] of String(text).split(/\r?\n/).entries()) {
+    const lineNumber = offset + 1;
+    if (rawLine.includes("\t")) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行不允许 Tab 缩进`);
+    }
+    const uncommented = stripYamlComment(rawLine).replace(/\s+$/, "");
+    if (!uncommented.trim()) continue;
+
+    const indent = uncommented.match(/^ */)[0].length;
+    if (![0, 2].includes(indent)) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行缩进非法`);
+    }
+    const content = uncommented.slice(indent);
+    const match = content.match(/^([A-Za-z_][A-Za-z0-9_-]*):(?:\s*(.*))?$/);
+    if (!match) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行格式非法`);
+    }
+    const [, key, rawValue = ""] = match;
+
+    if (indent === 0) {
+      section = null;
+      if (rootKeys.has(key)) {
+        throw new Error(`身份文件格式非法 ${relative}：重复字段 ${key}`);
+      }
+      rootKeys.add(key);
+      if (!rawValue.trim()) {
+        if (key !== "instantiation") {
+          throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行缺少值`);
+        }
+        root[key] = {};
+        section = key;
+      } else {
+        root[key] = parseYamlScalar(rawValue, relative, lineNumber);
+      }
+      continue;
+    }
+
+    if (section !== "instantiation" || !root.instantiation) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行存在未知嵌套`);
+    }
+    if (nestedKeys.has(key)) {
+      throw new Error(`身份文件格式非法 ${relative}：instantiation 重复字段 ${key}`);
+    }
+    nestedKeys.add(key);
+    const parsed = parseYamlScalar(rawValue, relative, lineNumber);
+    if (parsed === undefined) {
+      throw new Error(`身份文件格式非法 ${relative}：第 ${lineNumber} 行缺少值`);
+    }
+    root.instantiation[key] = parsed;
+  }
+
+  return root;
+}
+
+function createFamilyGuard(_packageRoot, expectedName) {
+  const expected = FAMILIES.find(({ name }) => name === expectedName);
+  if (!expected) throw new Error(`未知 CLI 家族：${expectedName}`);
+  const source = `github:iloveZzz/${expected.template}`;
+
+  function checkFields(value, fields, relative) {
+    for (const [key, wanted] of Object.entries(fields)) {
+      if (
+        Object.hasOwn(value, key) &&
+        (wanted === null || value[key] !== wanted)
+      ) {
+        throw new Error(
+          `身份不一致：${relative} 的 ${key} 与 ${expectedName} 不匹配；--force 不能绕过`,
+        );
+      }
+    }
+  }
+
+  return function checkTargetFamily(targetDir, { snapshot } = {}) {
+    const present = FAMILIES.filter(({ metadata }) =>
+      statOrMissing(path.join(targetDir, metadata)),
+    );
+    if (present.length > 1) {
+      throw new Error("目标存在多个模板家族身份；请人工核对，CLI 不自动修复");
+    }
+    if (present.length && present[0].name !== expectedName) {
+      throw new Error(
+        `目标身份属于 ${present[0].name}（${present[0].metadata}），不能使用 ${expectedName}；不支持跨家族迁移，--force 不能绕过`,
+      );
+    }
+
+    if (present.length) {
+      const metadataText = readIdentityFile(targetDir, expected.metadata);
+      const value = parseJsonObject(metadataText, expected.metadata);
+      if (
+        Object.hasOwn(value, "metadataSchemaVersion") &&
+        (!Number.isInteger(value.metadataSchemaVersion) ||
+          value.metadataSchemaVersion < 1 ||
+          value.metadataSchemaVersion > (expectedName === "create-yss-spec" ? 2 : 1))
+      ) {
+        throw new Error("身份 metadata schema 版本非法或不支持");
+      }
+      const legacy =
+        value.metadataSchemaVersion === undefined ||
+        (expectedName === "create-yss-spec" && value.metadataSchemaVersion === 1);
+      checkFields(
+        value,
+        {
+          templateName: expectedName,
+          templateSource:
+            legacy && value.templateSource === "legacy-attach"
+              ? "legacy-attach"
+              : source,
+          template_source: source,
+          profileId: expected.profile,
+          profile_id: expected.profile,
+        },
+        expected.metadata,
+      );
+    }
+
+    const profileText = readIdentityFile(targetDir, PROFILE_PATH);
+    if (profileText !== null) {
+      const profile = parseProfileYaml(profileText, PROFILE_PATH);
+      if (
+        profile.schema_version !== 1 ||
+        !FAMILIES.some(
+          (family) =>
+            family.profile !== null && family.profile === profile.profile_id,
+        )
+      ) {
+        throw new Error(`未知或非法 profile：${PROFILE_PATH}`);
+      }
+      if (expected.profile === null || profile.profile_id !== expected.profile) {
+        throw new Error(
+          `profile 身份与 ${expectedName} 不一致；不支持跨家族迁移，--force 不能绕过`,
+        );
+      }
+      if (profile.instantiation !== undefined) {
+        if (
+          !profile.instantiation ||
+          typeof profile.instantiation !== "object" ||
+          Array.isArray(profile.instantiation)
+        ) {
+          throw new Error(`profile 身份配置非法：${PROFILE_PATH}`);
+        }
+        checkFields(
+          profile.instantiation,
+          {
+            metadata_file: expected.metadata,
+            template_source: source,
+            cli_package: expectedName,
+          },
+          PROFILE_PATH,
+        );
+      }
+    }
+
+    if (snapshot) {
+      if (
+        snapshot.templateName !== expected.template ||
+        snapshot.templateSource !== source ||
+        (expected.profile
+          ? snapshot.profileId !== expected.profile || profileText === null
+          : Object.hasOwn(snapshot, "profileId"))
+      ) {
+        throw new Error(`模板快照家族身份与 ${expectedName} 不一致`);
+      }
+    }
+  };
+}
+
+module.exports = {
+  FAMILIES,
+  PROFILE_PATH,
+  parseProfileYaml,
+  createFamilyGuard,
+};

package/src/family-runtime.js

@@ -0,0 +1,23 @@
+"use strict";
+
+const path = require("node:path");
+const packageManifest = require("../package.json");
+const { createFamilyGuard } = require("./family-identity");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+const checkTargetFamily = createFamilyGuard(PACKAGE_ROOT, packageManifest.name);
+
+function assertBundledFamily(snapshot) {
+  checkTargetFamily(BUNDLED_TEMPLATE_ROOT, { snapshot });
+  return snapshot;
+}
+
+function assertTargetFamily(targetDir) {
+  checkTargetFamily(path.resolve(targetDir));
+}
+
+module.exports = {
+  assertBundledFamily,
+  assertTargetFamily,
+};

package/src/filesystem/apply-plan.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const fs = require("node:fs");
+const { targetPath } = require("./path-utils");
+
+function applyMigrationOperations(migrationPlan, transaction) {
+  for (const operation of migrationPlan.operations || []) {
+    if (operation.kind === "remove") {
+      transaction.remove(targetPath(migrationPlan.targetDir, operation.path));
+      continue;
+    }
+    if (operation.kind === "move") {
+      transaction.move(
+        targetPath(migrationPlan.targetDir, operation.from),
+        targetPath(migrationPlan.targetDir, operation.to),
+      );
+      continue;
+    }
+    throw new Error(`不支持的迁移操作：${operation.kind}`);
+  }
+}
+
+function applyManagedOperation(operation, transaction) {
+  if (operation.type === "render") {
+    transaction.ensureParent(operation.targetPath);
+    fs.writeFileSync(operation.targetPath, operation.desiredContent);
+    fs.chmodSync(operation.targetPath, fs.statSync(operation.sourcePath).mode & 0o777);
+    transaction.mark(operation.targetPath);
+    return;
+  }
+
+  if (operation.type === "copy") {
+    transaction.copyFile(operation.sourcePath, operation.targetPath);
+    fs.chmodSync(operation.targetPath, fs.statSync(operation.sourcePath).mode & 0o777);
+    return;
+  }
+
+  throw new Error(`不支持的受管操作：${operation.type}`);
+}
+
+module.exports = {
+  applyMigrationOperations,
+  applyManagedOperation,
+};

package/src/filesystem/copy-path.js

@@ -0,0 +1,28 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { pathKind } = require("./path-utils");
+
+function copyPath(sourcePath, destinationPath) {
+  const kind = pathKind(sourcePath);
+  if (kind === "other") {
+    throw new Error(`拒绝复制符号链接或特殊文件：${sourcePath}`);
+  }
+  if (kind === "missing") {
+    throw new Error(`复制源路径不存在：${sourcePath}`);
+  }
+
+  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+  if (kind === "directory") {
+    fs.cpSync(sourcePath, destinationPath, { recursive: true, force: true });
+    return;
+  }
+
+  fs.copyFileSync(sourcePath, destinationPath);
+  fs.chmodSync(destinationPath, fs.statSync(sourcePath).mode & 0o777);
+}
+
+module.exports = {
+  copyPath,
+};

package/src/filesystem/path-utils.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function normalizeRelativePath(value) {
+  return String(value || "")
+    .replaceAll("\\", "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+}
+
+function pathKind(absolutePath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(absolutePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return "missing";
+    throw error;
+  }
+  if (stat.isDirectory()) return "directory";
+  if (stat.isFile()) return "file";
+  return "other";
+}
+
+function targetPath(targetDir, relativePath) {
+  const root = path.resolve(targetDir);
+  const normalized = normalizeRelativePath(relativePath);
+  const resolved = path.resolve(root, normalized);
+  const relative = path.relative(root, resolved);
+
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error(`模板路径越界：${relativePath}`);
+  }
+
+  if (pathKind(root) === "directory") {
+    let current = root;
+    const segments = relative.split(path.sep).filter(Boolean);
+    segments.forEach((segment, index) => {
+      current = path.join(current, segment);
+      const kind = pathKind(current);
+      if (kind === "missing") return;
+
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink() && index < segments.length - 1) {
+        throw new Error(
+          `模板目标路径包含中间符号链接，无法安全写入：${relativePath}`,
+        );
+      }
+      if (index < segments.length - 1 && kind !== "directory") {
+        throw new Error(`模板目标父路径不是目录：${relativePath}`);
+      }
+    });
+  }
+
+  return resolved;
+}
+
+module.exports = {
+  normalizeRelativePath,
+  targetPath,
+  pathKind,
+};

package/src/filesystem/transaction-runner.js

@@ -0,0 +1,41 @@
+"use strict";
+
+const { FileTransaction } = require("./transaction");
+
+function runInTransaction({
+  targetDir,
+  affectedPaths = [],
+  execute,
+  operation = "operation",
+  TransactionClass = FileTransaction,
+}) {
+  if (typeof execute !== "function") {
+    throw new TypeError("runInTransaction requires execute callback");
+  }
+
+  const transaction = new TransactionClass(targetDir);
+
+  try {
+    transaction.prepare(affectedPaths);
+    const result = execute(transaction);
+    const backupPath = transaction.finish();
+    return {
+      result,
+      backupPath,
+      transaction,
+    };
+  } catch (error) {
+    try {
+      transaction.rollback();
+    } catch (rollbackError) {
+      throw new Error(`${error.message}\n回滚失败：${rollbackError.message}`);
+    }
+    throw new Error(
+      `${error.message}\n已回滚本次 ${operation}；临时备份保留于 ${transaction.backupRoot}`,
+    );
+  }
+}
+
+module.exports = {
+  runInTransaction,
+};