create-yss-spec 3.1.0 → 3.2.0

package/src/commands/attach.js

@@ -0,0 +1,280 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { parseArgs } = require("../cli/args");
+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 { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
+const { buildAttachPlanFromRuntime } = require("../template/attach-planner-runtime");
+const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const {
+  PACKAGE_ROOT,
+  BUNDLED_TEMPLATE_ROOT,
+  TEMPLATE_METADATA_FILENAME,
+  fileHash,
+  readTemplateSnapshot,
+  readTargetIdentity,
+  buildAttachDesiredOperations,
+  buildMetadata,
+  writeTemplateMetadata,
+} = require("../template/instance-runtime");
+const { verifyGeneratedAttach } = require("../template/verification-runtime");
+
+function assertRequiredOptions(options) {
+  if (!options.projectName) {
+    throw new Error("attach 需要 --project-name，项目名称不能为空");
+  }
+  if (!options.businessDomain) {
+    throw new Error("attach 需要 --business-domain，业务领域不能为空");
+  }
+  if (!options.targetDir) {
+    throw new Error("attach 需要 --target-dir，目标目录不能为空");
+  }
+}
+
+function normalizeTargetDir(targetDir) {
+  return path.resolve(process.cwd(), targetDir);
+}
+
+function isInsideTemplateRoot(targetDir) {
+  const relativePath = path.relative(BUNDLED_TEMPLATE_ROOT, targetDir);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+  );
+}
+
+function inspectExistingTargetDir(targetDir, { force = false } = {}) {
+  if (isInsideTemplateRoot(targetDir)) {
+    throw new Error("目标目录不能位于模板源仓库内部");
+  }
+  if (!fs.existsSync(targetDir) || pathKind(targetDir) !== "directory") {
+    throw new Error("attach 目标目录必须是已经存在的项目目录");
+  }
+  assertTargetWorkingTreeWritable(targetDir, {
+    force,
+    packageRoot: PACKAGE_ROOT,
+  });
+}
+
+function attachVariables(options) {
+  return {
+    projectName: options.projectName,
+    businessDomain: options.businessDomain,
+    teamSize: options.teamSize || "待补充",
+    issueTracker: options.issueTracker || "github",
+    includeExampleDocs:
+      options.includeExampleDocs === undefined
+        ? true
+        : Boolean(options.includeExampleDocs),
+  };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function printLimitedOperations(operations, formatter, limit = 40) {
+  const prioritized = [...operations].sort((left, right) => {
+    const leftPath = typeof left === "string" ? left : left.relativePath;
+    const rightPath = typeof right === "string" ? right : right.relativePath;
+    const leftIsRoot = !leftPath.includes("/");
+    const rightIsRoot = !rightPath.includes("/");
+    if (leftIsRoot !== rightIsRoot) return leftIsRoot ? -1 : 1;
+    return leftPath.localeCompare(rightPath);
+  });
+
+  for (const operation of prioritized.slice(0, limit)) {
+    console.log(formatter(operation));
+  }
+  if (operations.length > limit) {
+    console.log(
+      `... 其余 ${operations.length - limit} 项省略，可用 manifest / git diff 查看完整清单`,
+    );
+  }
+}
+
+function printMigrationPlan(migrationPlan) {
+  for (const item of migrationPlan.legacy || []) {
+    const destination = item.to ? ` -> ${item.to}` : "";
+    console.log(`legacy: ${item.action} ${item.from}${destination}`);
+  }
+  for (const item of migrationPlan.unsafe || []) {
+    console.log(`unsafe: ${item.path} (${item.reason})`);
+  }
+  for (const item of migrationPlan.conflicts || []) {
+    console.log(`conflict: ${item.from} -> ${item.to} (${item.reason})`);
+  }
+}
+
+function printAttachDryRun(plan, targetDir) {
+  console.log("attach dry-run 预览");
+  console.log(`目标目录：${targetDir}`);
+  printLimitedOperations(
+    plan.missing,
+    (operation) => `add: ${operation.relativePath}`,
+  );
+  printLimitedOperations(
+    plan.identity,
+    (operation) => `identity: ${operation.relativePath}（规范化为 project-instance）`,
+  );
+  printLimitedOperations(
+    plan.conflicts,
+    (operation) => `conflict: ${operation.relativePath} (${operation.reason})`,
+  );
+  printLimitedOperations(
+    plan.unsafe,
+    (operation) => `unsafe: ${operation.relativePath} (${operation.reason})`,
+  );
+  if (plan.matched.length > 0) {
+    console.log(`matched: ${plan.matched.length} 项内容一致，已纳入 managed baseline`);
+  }
+  printMigrationPlan(plan.migration);
+  console.log(
+    `统计：新增 ${plan.missing.length}，一致 ${plan.matched.length}，身份转换 ${plan.identity.length}，冲突 ${plan.conflicts.length}，unsafe ${plan.unsafe.length}`,
+  );
+  if (plan.conflicts.length > 0) {
+    console.log("提示：--force 只覆盖 forceable 冲突；mergeStrategy=manual 的冲突必须人工处理");
+  }
+}
+
+function affectedPathsForManagedOperations(operations) {
+  return operations.map((operation) => normalizeRelativePath(operation.relativePath));
+}
+
+function affectedPathsForMigration(migrationPlan) {
+  return (migrationPlan.operations || []).flatMap((operation) =>
+    operation.kind === "move" ? [operation.from, operation.to] : [operation.path],
+  );
+}
+
+function runAttach(argv = []) {
+  const options = parseArgs(argv);
+  assertRequiredOptions(options);
+
+  if (options.dryRun && options.apply) {
+    throw new Error("attach 的 --dry-run 与 --apply 互斥");
+  }
+  if (!options.dryRun && !options.apply) {
+    throw new Error("attach 必须显式传入 --dry-run 或 --apply");
+  }
+
+  const snapshot = readTemplateSnapshot();
+  assertBundledFamily(snapshot);
+  const targetDir = normalizeTargetDir(options.targetDir);
+  assertTargetFamily(targetDir);
+  inspectExistingTargetDir(targetDir, { force: Boolean(options.force) });
+
+  if (pathKind(targetPath(targetDir, TEMPLATE_METADATA_FILENAME)) !== "missing") {
+    throw new Error("当前项目已有模板元数据，请使用 sync，不要重复 attach");
+  }
+
+  const variables = attachVariables(options);
+  const identity = readTargetIdentity(targetDir);
+  const desiredOperations = buildAttachDesiredOperations(
+    targetDir,
+    variables,
+    identity,
+  );
+  const migrationPlan = buildLegacyMigrationPlan(targetDir, desiredOperations, {
+    checkFlatTickets: true,
+  });
+  const warning = gitDirtyWarning(targetDir);
+
+  const { classified: plan } = buildAttachPlanFromRuntime({
+    targetDir,
+    desiredOperations,
+    migration: migrationPlan,
+    warning,
+    getUnmanagedReason: (operation) =>
+      unmanagedPathReason(targetDir, operation.relativePath, {
+        packageRoot: PACKAGE_ROOT,
+      }),
+    getPathKind: (operation) => pathKind(operation.targetPath),
+    getFileHash: (operation) => fileHash(operation.targetPath),
+  });
+  plan.migration = migrationPlan;
+
+  if (warning) console.log(warning);
+
+  if (options.dryRun) {
+    printAttachDryRun(plan, targetDir);
+    return;
+  }
+
+  if (migrationPlan.unsafe.length > 0) {
+    printMigrationPlan(migrationPlan);
+    throw new Error(
+      "attach 被 unsafe 迁移项阻断；--force 不能绕过，请先人工整理 Ticket 归属",
+    );
+  }
+  if (plan.unsafe.length > 0) {
+    printAttachDryRun(plan, targetDir);
+    throw new Error(
+      "attach 被 unsafe 受管路径阻断；--force 不能绕过，请先人工整理目标路径",
+    );
+  }
+  if (migrationPlan.conflicts.length > 0) {
+    printMigrationPlan(migrationPlan);
+    throw new Error("attach 被旧路径迁移冲突阻断，请先处理目标冲突");
+  }
+  if (plan.conflicts.length > 0 && !options.force) {
+    printAttachDryRun(plan, targetDir);
+    throw new Error(
+      "attach 检测到受管文件冲突；请先 dry-run，再使用 --apply --force",
+    );
+  }
+
+  const managedToApply = [
+    ...plan.missing,
+    ...plan.identity,
+    ...(options.force ? plan.forceableConflicts : []),
+  ];
+
+  const { backupPath } = runInTransaction({
+    targetDir,
+    operation: "attach",
+    affectedPaths: [
+      ...affectedPathsForManagedOperations(managedToApply),
+      ...affectedPathsForMigration(migrationPlan),
+      TEMPLATE_METADATA_FILENAME,
+    ],
+    execute: (transaction) => {
+      for (const operation of managedToApply) {
+        applyManagedOperation(operation, transaction);
+      }
+      applyMigrationOperations(migrationPlan, transaction);
+      verifyGeneratedAttach(targetDir);
+      writeTemplateMetadata(
+        targetDir,
+        buildMetadata(variables, desiredOperations),
+        transaction,
+      );
+    },
+  });
+
+  console.log("接管完成");
+  console.log(`目标目录：${targetDir}`);
+  console.log(`新增研发管理资产：${plan.missing.length + plan.identity.length}`);
+  if (options.force && plan.forceableConflicts.length > 0) {
+    console.log(`force 覆盖冲突：${plan.forceableConflicts.length}`);
+  }
+  const manualConflicts = plan.conflicts.length - plan.forceableConflicts.length;
+  if (manualConflicts > 0) {
+    console.log(`需人工处理冲突：${manualConflicts}`);
+  }
+  if (backupPath) {
+    console.log(`备份目录：${backupPath}`);
+    console.log(`清理命令：rm -rf ${shellQuote(backupPath)}`);
+  }
+  console.log("下一步建议：运行 git diff 或 git status 检查接管结果");
+}
+
+module.exports = {
+  runAttach,
+};

package/src/commands/diff.js

@@ -0,0 +1,23 @@
+"use strict";
+
+const { parseArgs } = require("../cli/args");
+const { renderPlanText } = require("../cli/plan-output");
+const { serializePlan } = require("../template/plan-schema");
+const { projectDiff } = require("../api/project-diff");
+
+function runDiff(argv = []) {
+  const options = parseArgs(argv);
+  const plan = projectDiff({
+    targetDir: options.targetDir || ".",
+    force: Boolean(options.force),
+  });
+
+  if (options.json) {
+    process.stdout.write(serializePlan(plan));
+  } else {
+    process.stdout.write(renderPlanText(plan));
+  }
+  return plan;
+}
+
+module.exports = { runDiff };

package/src/commands/doctor.js

@@ -0,0 +1,417 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const { parseArgs } = require("../cli/args");
+const { pathKind, targetPath } = require("../filesystem/path-utils");
+const { gitDirtyWarning } = require("../git/worktree");
+const { gitlinkWriteViolation } = require("../validation/security");
+const {
+  PACKAGE_ROOT,
+  PACKAGE_MANIFEST,
+  fileHash,
+  readTemplateSnapshot,
+  readTargetIdentity,
+  loadTemplateMetadata,
+} = require("../template/instance-runtime");
+const {
+  ownershipPolicyDrift,
+} = require("../template/ownership-metadata");
+const {
+  lifecyclePolicyDrift,
+} = require("../template/lifecycle-metadata");
+
+const DOCTOR_SCHEMA_VERSION = 1;
+const VERIFIERS = [
+  {
+    name: "verifier-sync-skills",
+    path: "scripts/sync-skills",
+    args: ["--check"],
+  },
+  {
+    name: "verifier-skill-lock",
+    path: "scripts/update-skill-lock",
+    args: ["--check"],
+  },
+  {
+    name: "verifier-template",
+    path: "scripts/verify-template",
+    args: [],
+    requiresGit: true,
+  },
+];
+
+function normalizeTargetDir(value) {
+  return path.resolve(process.cwd(), value || ".");
+}
+
+function addCheck(report, name, status, detail, data = undefined) {
+  const check = { name, status, detail };
+  if (data !== undefined) check.data = data;
+  report.checks.push(check);
+  if (status === "error") report.ok = false;
+  return check;
+}
+
+function isGitWorktree(targetDir) {
+  const result = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: targetDir,
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return result.status === 0 && (result.stdout || "").trim() === "true";
+}
+
+function checkManagedBaseline(report, targetDir, metadata) {
+  const managedFiles = metadata.managedFiles || {};
+  const stats = {
+    total: 0,
+    matched: 0,
+    modified: 0,
+    missing: 0,
+    invalid: 0,
+  };
+
+  for (const [relativePath, record] of Object.entries(managedFiles)) {
+    stats.total += 1;
+    if (
+      !record ||
+      typeof record !== "object" ||
+      Array.isArray(record) ||
+      !/^[0-9a-f]{64}$/.test(record.contentHash || "")
+    ) {
+      stats.invalid += 1;
+      continue;
+    }
+
+    let absolutePath;
+    try {
+      absolutePath = targetPath(targetDir, relativePath);
+    } catch {
+      stats.invalid += 1;
+      continue;
+    }
+
+    const kind = pathKind(absolutePath);
+    if (kind === "missing") {
+      stats.missing += 1;
+      continue;
+    }
+    if (kind !== "file") {
+      stats.invalid += 1;
+      continue;
+    }
+
+    if (fileHash(absolutePath) === record.contentHash) {
+      stats.matched += 1;
+    } else {
+      stats.modified += 1;
+    }
+  }
+
+  if (stats.invalid > 0) {
+    addCheck(
+      report,
+      "managed-baseline",
+      "error",
+      `managed baseline 含 ${stats.invalid} 个非法记录或不安全路径`,
+      stats,
+    );
+  } else if (stats.missing > 0 || stats.modified > 0) {
+    addCheck(
+      report,
+      "managed-baseline",
+      "warning",
+      `受管基线存在漂移：本地修改 ${stats.modified}，缺失 ${stats.missing}`,
+      stats,
+    );
+  } else {
+    addCheck(
+      report,
+      "managed-baseline",
+      "ok",
+      `受管基线一致：${stats.matched}/${stats.total}`,
+      stats,
+    );
+  }
+}
+
+function checkOwnershipPolicy(report, metadata) {
+  const drift = ownershipPolicyDrift(metadata);
+  if (drift.state === "missing") {
+    addCheck(
+      report,
+      "ownership-policy",
+      "warning",
+      "实例 metadata 尚未记录 ownership policy baseline；下一次 attach/sync 会自动补齐",
+      drift,
+    );
+    return;
+  }
+  if (drift.state === "drift") {
+    addCheck(
+      report,
+      "ownership-policy",
+      "warning",
+      `ownership policy baseline 与当前 CLI 不一致：v${drift.actualVersion} -> v${drift.expectedVersion}`,
+      drift,
+    );
+    return;
+  }
+  addCheck(
+    report,
+    "ownership-policy",
+    "ok",
+    `ownership policy baseline 一致：v${drift.expectedVersion}`,
+    drift,
+  );
+}
+
+function addLifecycleDriftCheck(report, name, label, drift) {
+  if (drift.state === "missing") {
+    addCheck(
+      report,
+      name,
+      "warning",
+      `实例 metadata 尚未记录 ${label} baseline；下一次 attach/sync 会自动补齐`,
+      drift,
+    );
+    return;
+  }
+  if (drift.state === "drift") {
+    addCheck(
+      report,
+      name,
+      "warning",
+      `${label} baseline 与当前 CLI 不一致：v${drift.actual.version} -> v${drift.expected.version}`,
+      drift,
+    );
+    return;
+  }
+  addCheck(
+    report,
+    name,
+    "ok",
+    `${label} baseline 一致：v${drift.expected.version}`,
+    drift,
+  );
+}
+
+function checkLifecyclePolicies(report, metadata) {
+  const drift = lifecyclePolicyDrift(metadata);
+  addLifecycleDriftCheck(
+    report,
+    "customization-policy",
+    "customization policy",
+    drift.customization,
+  );
+  addLifecycleDriftCheck(
+    report,
+    "generator-policy",
+    "generator policy",
+    drift.generator,
+  );
+}
+
+function runVerifierCheck(report, targetDir, verifier, gitWorktree) {
+  const commandPath = targetPath(targetDir, verifier.path);
+  if (pathKind(commandPath) !== "file") {
+    addCheck(
+      report,
+      verifier.name,
+      "error",
+      `缺少 verifier：${verifier.path}`,
+    );
+    return;
+  }
+
+  if (verifier.requiresGit && !gitWorktree) {
+    addCheck(
+      report,
+      verifier.name,
+      "warning",
+      `未执行 ${verifier.path}：目标目录不是 Git worktree；doctor 不会临时 git init`,
+    );
+    return;
+  }
+
+  const result = spawnSync(commandPath, verifier.args || [], {
+    cwd: targetDir,
+    encoding: "utf8",
+    timeout: 30000,
+  });
+  const output = [result.stdout, result.stderr]
+    .filter(Boolean)
+    .join("")
+    .trim();
+
+  if (result.error || result.status !== 0) {
+    addCheck(
+      report,
+      verifier.name,
+      "error",
+      `${verifier.path} 校验失败${output ? `：${output}` : ""}`,
+      { exitCode: result.status },
+    );
+    return;
+  }
+
+  addCheck(
+    report,
+    verifier.name,
+    "ok",
+    `${verifier.path} 校验通过`,
+    { exitCode: result.status },
+  );
+}
+
+function buildDoctorReport(targetDir) {
+  const report = {
+    schemaVersion: DOCTOR_SCHEMA_VERSION,
+    operation: "doctor",
+    targetDir,
+    cliVersion: PACKAGE_MANIFEST.version,
+    ok: true,
+    checks: [],
+  };
+
+  let snapshot = null;
+  try {
+    snapshot = readTemplateSnapshot();
+    addCheck(
+      report,
+      "template-snapshot",
+      "ok",
+      `模板快照有效：${snapshot.templateCommit}`,
+      { templateCommit: snapshot.templateCommit },
+    );
+  } catch (error) {
+    addCheck(report, "template-snapshot", "error", error.message);
+  }
+
+  if (!fs.existsSync(targetDir) || pathKind(targetDir) !== "directory") {
+    addCheck(report, "target-directory", "error", "目标目录不存在或不是目录");
+    return report;
+  }
+  addCheck(report, "target-directory", "ok", "目标目录可读取");
+
+  const violation = gitlinkWriteViolation(targetDir, {
+    packageRoot: PACKAGE_ROOT,
+  });
+  if (violation) {
+    addCheck(report, "git-safety", "error", violation);
+  } else {
+    addCheck(report, "git-safety", "ok", "未检测到 gitlink / detached HEAD 写入风险");
+  }
+
+  let metadata = null;
+  try {
+    ({ metadata } = loadTemplateMetadata(targetDir));
+    addCheck(
+      report,
+      "template-metadata",
+      "ok",
+      `模板元数据有效：${metadata.templateVersion || metadata.cliVersion || "unknown"}`,
+      {
+        metadataSchemaVersion: metadata.metadataSchemaVersion,
+        templateVersion: metadata.templateVersion || metadata.cliVersion || null,
+        templateCommit: metadata.templateCommit || null,
+      },
+    );
+
+    if (snapshot && metadata.templateCommit !== snapshot.templateCommit) {
+      addCheck(
+        report,
+        "template-drift",
+        "warning",
+        `实例模板 commit 与当前 CLI 快照不同：${metadata.templateCommit} -> ${snapshot.templateCommit}`,
+        {
+          from: metadata.templateCommit,
+          to: snapshot.templateCommit,
+        },
+      );
+    } else if (snapshot) {
+      addCheck(report, "template-drift", "ok", "实例模板 commit 与当前 CLI 快照一致");
+    }
+
+    checkOwnershipPolicy(report, metadata);
+    checkLifecyclePolicies(report, metadata);
+    checkManagedBaseline(report, targetDir, metadata);
+  } catch (error) {
+    addCheck(report, "template-metadata", "error", error.message);
+  }
+
+  try {
+    const identity = readTargetIdentity(targetDir);
+    if (identity.state !== "valid") {
+      addCheck(report, "project-identity", "error", "缺少 yss-project.yaml");
+    } else if (identity.fields.repository_mode !== "project-instance") {
+      addCheck(
+        report,
+        "project-identity",
+        "error",
+        `repository_mode 不是 project-instance：${identity.fields.repository_mode}`,
+      );
+    } else {
+      addCheck(report, "project-identity", "ok", "yss-project.yaml 为 project-instance");
+    }
+  } catch (error) {
+    addCheck(report, "project-identity", "error", error.message);
+  }
+
+  const gitWorktree = isGitWorktree(targetDir);
+  const dirtyWarning = gitDirtyWarning(targetDir);
+  if (dirtyWarning) {
+    addCheck(report, "git-worktree", "warning", dirtyWarning);
+  } else if (gitWorktree) {
+    addCheck(report, "git-worktree", "ok", "Git worktree 无需警告");
+  } else {
+    addCheck(report, "git-worktree", "warning", "目标目录不是 Git worktree");
+  }
+
+  for (const verifier of VERIFIERS) {
+    runVerifierCheck(report, targetDir, verifier, gitWorktree);
+  }
+
+  return report;
+}
+
+function renderDoctorText(report) {
+  const lines = [
+    "create-yss-spec doctor",
+    `目标目录：${report.targetDir}`,
+    `结果：${report.ok ? "PASS" : "FAIL"}`,
+  ];
+  for (const check of report.checks) {
+    lines.push(`[${check.status.toUpperCase()}] ${check.name}: ${check.detail}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function runDoctor(argv = []) {
+  const options = parseArgs(argv);
+  const targetDir = normalizeTargetDir(options.targetDir);
+  const report = buildDoctorReport(targetDir);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(renderDoctorText(report));
+  }
+
+  return report;
+}
+
+module.exports = {
+  DOCTOR_SCHEMA_VERSION,
+  VERIFIERS,
+  checkManagedBaseline,
+  checkOwnershipPolicy,
+  checkLifecyclePolicies,
+  runVerifierCheck,
+  buildDoctorReport,
+  renderDoctorText,
+  runDoctor,
+};