create-yss-spec 3.1.0 → 3.2.0

package/src/commands/init.js

@@ -0,0 +1,193 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { parseArgs } = require("../cli/args");
+const { promptForMissingOptions } = require("../cli/prompts");
+const { printHelp, printVersion } = require("../cli/help");
+const { pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
+const { applyManagedOperation } = require("../filesystem/apply-plan");
+const { runInTransaction } = require("../filesystem/transaction-runner");
+const { assertBundledFamily, assertTargetFamily } = require("../family-runtime");
+const { assertTargetWorkingTreeWritable } = require("../validation/security");
+const {
+  PACKAGE_ROOT,
+  PACKAGE_MANIFEST,
+  BUNDLED_TEMPLATE_ROOT,
+  TEMPLATE_METADATA_FILENAME,
+  readTemplateSnapshot,
+  buildDesiredManagedOperations,
+  buildMetadata,
+  writeTemplateMetadata,
+} = require("../template/instance-runtime");
+const {
+  applyOwnershipToOperations,
+  assertWritableTemplateOperations,
+} = require("../template/ownership-runtime");
+const {
+  initializeGitRepository,
+  verifyGeneratedInit,
+} = require("../template/verification-runtime");
+
+function assertRequiredOptions(options) {
+  if (!options.projectName) {
+    throw new Error("init 需要 --project-name，项目名称不能为空");
+  }
+  if (!options.businessDomain) {
+    throw new Error("init 需要 --business-domain，业务领域不能为空");
+  }
+  if (!options.targetDir) {
+    throw new Error("init 需要 --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 inspectTargetDir(targetDir, force) {
+  if (isInsideTemplateRoot(targetDir)) {
+    throw new Error("目标目录不能位于模板源仓库内部");
+  }
+
+  assertTargetWorkingTreeWritable(targetDir, {
+    force,
+    packageRoot: PACKAGE_ROOT,
+  });
+
+  if (!fs.existsSync(targetDir)) {
+    return { exists: false, clearEntries: false };
+  }
+  if (pathKind(targetDir) !== "directory") {
+    throw new Error("目标目录必须是目录");
+  }
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length > 0 && !force) {
+    throw new Error("目标目录非空，当前主路径不支持覆盖已有内容");
+  }
+
+  return { exists: true, clearEntries: entries.length > 0 && force };
+}
+
+function prepareTargetDir(targetDir, targetState) {
+  if (!targetState.exists) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    return;
+  }
+  if (!targetState.clearEntries) return;
+
+  for (const entry of fs.readdirSync(targetDir)) {
+    fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
+  }
+}
+
+function parentDirectoryOperations(desiredOperations, targetDir) {
+  const directories = new Set();
+  for (const operation of desiredOperations) {
+    const parts = normalizeRelativePath(operation.relativePath).split("/").filter(Boolean);
+    parts.pop();
+    let current = "";
+    for (const part of parts) {
+      current = current ? `${current}/${part}` : part;
+      directories.add(current);
+    }
+  }
+
+  return [...directories]
+    .sort((left, right) => {
+      const depth = left.split("/").length - right.split("/").length;
+      return depth || left.localeCompare(right);
+    })
+    .map((relativePath) => ({
+      type: "mkdir",
+      relativePath,
+      targetPath: path.join(targetDir, ...relativePath.split("/")),
+    }));
+}
+
+async function runInit(argv = []) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp(PACKAGE_MANIFEST.version);
+    return;
+  }
+  if (options.version) {
+    printVersion(PACKAGE_MANIFEST.version);
+    return;
+  }
+
+  const promptedOptions = await promptForMissingOptions(options);
+  assertRequiredOptions(promptedOptions);
+  const snapshot = readTemplateSnapshot();
+  assertBundledFamily(snapshot);
+
+  const targetDir = normalizeTargetDir(promptedOptions.targetDir);
+  assertTargetFamily(targetDir);
+  const targetState = inspectTargetDir(targetDir, promptedOptions.force);
+  const desiredOperations = applyOwnershipToOperations(
+    buildDesiredManagedOperations(targetDir, promptedOptions, "init"),
+  );
+  assertWritableTemplateOperations(desiredOperations);
+  const directoryOperations = parentDirectoryOperations(desiredOperations, targetDir);
+
+  if (promptedOptions.dryRun) {
+    console.log("dry-run 预览");
+    console.log(`输出目录：${targetDir}`);
+    for (const operation of [...directoryOperations, ...desiredOperations]) {
+      const ownership = operation.ownership ? ` [${operation.ownership}]` : "";
+      console.log(`${operation.type}: ${operation.relativePath}${ownership}`);
+    }
+    return;
+  }
+
+  prepareTargetDir(targetDir, targetState);
+
+  runInTransaction({
+    targetDir,
+    operation: "init",
+    affectedPaths: [
+      ...desiredOperations.map((operation) => operation.relativePath),
+      TEMPLATE_METADATA_FILENAME,
+    ],
+    execute: (transaction) => {
+      for (const operation of desiredOperations) {
+        applyManagedOperation(operation, transaction);
+      }
+      verifyGeneratedInit(targetDir);
+      writeTemplateMetadata(
+        targetDir,
+        buildMetadata(promptedOptions, desiredOperations),
+        transaction,
+      );
+    },
+  });
+
+  if (promptedOptions.gitInit) {
+    initializeGitRepository(targetDir);
+  }
+
+  console.log("初始化完成");
+  console.log(`输出目录：${targetDir}`);
+  console.log("下一步建议：");
+  console.log(`1. cd ${targetDir}`);
+  console.log(
+    promptedOptions.gitInit
+      ? "2. 运行 git status 检查初始化结果"
+      : "2. 如需版本管理，可执行 git init",
+  );
+  console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
+}
+
+module.exports = {
+  runInit,
+};

package/src/commands/sync.js

@@ -0,0 +1,146 @@
+"use strict";
+
+const { parseArgs } = require("../cli/args");
+const { renderPlanText } = require("../cli/plan-output");
+const { serializePlan } = require("../template/plan-schema");
+const {
+  buildSyncContext,
+  applySyncContext,
+} = require("../api/_sync-service");
+
+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 printSyncDryRun(context) {
+  const { targetDir, metadata, syncPlan, migrationPlan, plan } = context;
+  console.log("sync dry-run 预览");
+  console.log(`目标目录：${targetDir}`);
+  console.log(
+    `模板版本：${metadata.templateVersion || metadata.cliVersion || "unknown"} -> ${plan.template?.to || "unknown"}`,
+  );
+  printLimitedOperations(
+    syncPlan.updated,
+    (operation) => `update: ${operation.relativePath}`,
+  );
+  printLimitedOperations(
+    syncPlan.added,
+    (operation) => `add: ${operation.relativePath}`,
+  );
+  printLimitedOperations(
+    syncPlan.skipped,
+    (operation) => `conflict: ${operation.relativePath} (${operation.reason})`,
+  );
+  printLimitedOperations(
+    syncPlan.unsafe,
+    (operation) => `unsafe: ${operation.relativePath} (${operation.reason})`,
+  );
+  printLimitedOperations(
+    syncPlan.removed,
+    (relativePath) => `remove-report: ${relativePath}`,
+  );
+  console.log(`unchanged: ${syncPlan.unchanged.length}`);
+  printMigrationPlan(migrationPlan);
+}
+
+function runSync(argv = []) {
+  const options = parseArgs(argv);
+  const context = buildSyncContext({
+    targetDir: options.targetDir || ".",
+    force: Boolean(options.force),
+  });
+
+  if (options.json) {
+    process.stdout.write(serializePlan(context.plan));
+    return context.plan;
+  }
+
+  if (options.plan) {
+    process.stdout.write(renderPlanText(context.plan));
+    return context.plan;
+  }
+
+  if (context.warning) console.log(context.warning);
+
+  if (options.dryRun) {
+    printSyncDryRun(context);
+    return context.plan;
+  }
+
+  if (context.migrationPlan.unsafe.length > 0 || context.syncPlan.unsafe.length > 0) {
+    printSyncDryRun(context);
+  } else if (context.migrationPlan.conflicts.length > 0) {
+    printMigrationPlan(context.migrationPlan);
+  }
+
+  const result = applySyncContext(context, { force: Boolean(options.force) });
+
+  console.log("同步完成");
+  console.log(
+    `模板版本：${context.metadata.templateVersion || context.metadata.cliVersion || "unknown"} -> ${context.plan.template?.to || "unknown"}`,
+  );
+  console.log(`自动更新：${result.stats.updated}`);
+  console.log(`新增文件：${result.stats.added}`);
+  console.log(`跳过文件：${result.stats.skipped}`);
+  console.log(`删除差异：${result.stats.removed}`);
+
+  if (result.skipped.length > 0) {
+    console.log("本地已修改，已跳过：");
+    for (const item of result.skipped) {
+      console.log(`- ${item.path}: ${item.reason}`);
+    }
+  }
+  if (result.removed.length > 0) {
+    console.log("模板已移除但未自动删除：");
+    for (const relativePath of result.removed) {
+      console.log(`- ${relativePath}`);
+    }
+  }
+  if (result.backupPath) {
+    console.log(`备份目录：${result.backupPath}`);
+    console.log(`清理命令：rm -rf ${shellQuote(result.backupPath)}`);
+  }
+
+  console.log("下一步建议：");
+  console.log("1. 运行 git diff 或 git status 检查同步结果");
+  console.log("2. 人工处理被跳过文件和删除差异（如有）");
+  console.log("3. 确认无误后提交本次模板同步结果");
+  return result;
+}
+
+module.exports = {
+  runSync,
+};

package/src/commands/update.js

@@ -0,0 +1,14 @@
+"use strict";
+
+const { runUpdate } = require("../self-update");
+
+function runUpdateCommand(argv = [], context) {
+  return runUpdate(argv, {
+    packageRoot: context.packageRoot,
+    currentVersion: context.currentVersion,
+  });
+}
+
+module.exports = {
+  runUpdateCommand,
+};

package/src/contracts/apply-result-v1.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/apply-result-v1.json",
+  "title": "create-yss-spec Apply Result v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "operation", "targetDir", "backupPath", "template", "stats", "skipped", "removed"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "operation": { "const": "sync" },
+    "targetDir": { "type": "string", "minLength": 1 },
+    "backupPath": { "type": ["string", "null"] },
+    "template": { "type": ["object", "null"], "additionalProperties": true },
+    "stats": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["updated", "added", "skipped", "removed", "forceApplied"],
+      "properties": {
+        "updated": { "type": "integer", "minimum": 0 },
+        "added": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 },
+        "removed": { "type": "integer", "minimum": 0 },
+        "forceApplied": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "skipped": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason", "ownership", "mergeStrategy"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 },
+          "ownership": { "type": ["string", "null"] },
+          "mergeStrategy": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "removed": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/src/contracts/customization-policy-v1.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/customization-policy-v1.json",
+  "title": "create-yss-spec Customization Policy v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "defaultStrategy", "rules"],
+  "properties": {
+    "version": { "const": 1 },
+    "defaultStrategy": {
+      "enum": ["replace-with-force", "manual"]
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern", "strategy"],
+        "properties": {
+          "pattern": { "type": "string", "minLength": 1 },
+          "strategy": {
+            "enum": ["replace-with-force", "manual"]
+          }
+        }
+      }
+    }
+  }
+}

package/src/contracts/doctor-report-v1.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/doctor-report-v1.json",
+  "title": "create-yss-spec Doctor Report v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "operation", "targetDir", "cliVersion", "ok", "checks"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "operation": { "const": "doctor" },
+    "targetDir": { "type": "string", "minLength": 1 },
+    "cliVersion": { "type": "string", "minLength": 1 },
+    "ok": { "type": "boolean" },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "status", "detail"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["ok", "warning", "error"] },
+          "detail": { "type": "string", "minLength": 1 },
+          "data": {}
+        }
+      }
+    }
+  }
+}

package/src/contracts/error-envelope-v1.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/error-envelope-v1.json",
+  "title": "create-yss-spec Error Envelope v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "ok", "error"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "ok": { "const": false },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^YSS_[A-Z0-9_]+$"
+        },
+        "message": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/src/contracts/generator-policy-v1.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/generator-policy-v1.json",
+  "title": "create-yss-spec Generator Policy v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "rules"],
+  "properties": {
+    "version": { "const": 1 },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern", "generatorId", "generatorVersion"],
+        "properties": {
+          "pattern": { "type": "string", "minLength": 1 },
+          "generatorId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "generatorVersion": { "type": "integer", "minimum": 1 }
+        }
+      }
+    }
+  }
+}

package/src/contracts/ownership-policy-v1.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/ownership-policy-v1.json",
+  "title": "create-yss-spec Ownership Policy v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "default", "rules"],
+  "properties": {
+    "version": { "const": 1 },
+    "default": {
+      "enum": [
+        "managed",
+        "managed-customizable",
+        "generated",
+        "user-owned",
+        "protected"
+      ]
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern", "ownership"],
+        "properties": {
+          "pattern": { "type": "string", "minLength": 1 },
+          "ownership": {
+            "enum": [
+              "managed",
+              "managed-customizable",
+              "generated",
+              "user-owned",
+              "protected"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/src/contracts/plan-schema-v1.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/iloveZzz/create-yss-spec/schemas/plan-v1.json",
+  "title": "create-yss-spec Plan Schema v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "operation",
+    "targetDir",
+    "template",
+    "changes",
+    "conflicts",
+    "unsafe",
+    "warnings",
+    "blocked",
+    "stats",
+    "migration"
+  ],
+  "$defs": {
+    "ownership": {
+      "enum": [
+        "managed",
+        "managed-customizable",
+        "generated",
+        "user-owned",
+        "protected"
+      ]
+    },
+    "mergeStrategy": {
+      "enum": ["replace-with-force", "manual"]
+    },
+    "generatorId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "generatorVersion": {
+      "type": "integer",
+      "minimum": 1
+    }
+  },
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "operation": { "type": "string", "minLength": 1 },
+    "targetDir": { "type": ["string", "null"] },
+    "template": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["action", "path"],
+        "properties": {
+          "action": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "ownership": { "$ref": "#/$defs/ownership" },
+          "mergeStrategy": { "$ref": "#/$defs/mergeStrategy" },
+          "generatorId": { "$ref": "#/$defs/generatorId" },
+          "generatorVersion": { "$ref": "#/$defs/generatorVersion" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "conflicts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string" },
+          "forceable": { "type": "boolean" },
+          "source": { "type": "string" },
+          "ownership": { "$ref": "#/$defs/ownership" },
+          "mergeStrategy": { "$ref": "#/$defs/mergeStrategy" },
+          "generatorId": { "$ref": "#/$defs/generatorId" },
+          "generatorVersion": { "$ref": "#/$defs/generatorVersion" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "unsafe": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string" },
+          "source": { "type": "string" },
+          "ownership": { "$ref": "#/$defs/ownership" },
+          "mergeStrategy": { "$ref": "#/$defs/mergeStrategy" },
+          "generatorId": { "$ref": "#/$defs/generatorId" },
+          "generatorVersion": { "$ref": "#/$defs/generatorVersion" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "blocked": { "type": "boolean" },
+    "stats": {
+      "type": "object",
+      "additionalProperties": { "type": "number" }
+    },
+    "migration": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    }
+  }
+}