create-yss-spec 3.1.0 → 3.2.0

package/src/cli/error-output.js

@@ -0,0 +1,52 @@
+"use strict";
+
+const ERROR_SCHEMA_VERSION = 1;
+
+const ERROR_RULES = [
+  [/模板路径越界|中间符号链接|目标父路径不是目录|符号链接或特殊文件/, "YSS_PATH_SAFETY"],
+  [/gitlink|git-submodule|detached HEAD|submodule/, "YSS_GIT_PROTECTED"],
+  [/模板家族|家族身份|多个模板家族|目标身份属于|profile 身份|身份不一致|身份文件格式非法|身份 metadata schema|未知或非法 profile|不支持跨家族迁移/, "YSS_FAMILY_IDENTITY_INVALID"],
+  [/ownership policy|user-owned|被 ownership policy 标记为 protected/, "YSS_OWNERSHIP_PROTECTED"],
+  [/模板快照|snapshotHash|templateCommit/, "YSS_SNAPSHOT_INVALID"],
+  [/模板元数据|metadataSchemaVersion|managedFilesManifestVersion/, "YSS_METADATA_INVALID"],
+  [/yss-project\.yaml|repository_mode|schema_version/, "YSS_IDENTITY_INVALID"],
+  [/迁移冲突|迁移目标|旧路径迁移冲突/, "YSS_MIGRATION_CONFLICT"],
+  [/unsafe|受管路径阻断|人工整理 Ticket/, "YSS_UNSAFE_PATH"],
+  [/不支持的参数|需要 --|需要一个值|--dry-run 与 --apply|必须显式传入/, "YSS_ARGUMENT_INVALID"],
+  [/目标目录|目标路径/, "YSS_TARGET_INVALID"],
+];
+
+function classifyErrorCode(error) {
+  if (error && typeof error.code === "string" && error.code.startsWith("YSS_")) {
+    return error.code;
+  }
+
+  const message = String(error?.message || error || "");
+  for (const [pattern, code] of ERROR_RULES) {
+    if (pattern.test(message)) return code;
+  }
+  return "YSS_COMMAND_FAILED";
+}
+
+function normalizeError(error) {
+  return {
+    schemaVersion: ERROR_SCHEMA_VERSION,
+    ok: false,
+    error: {
+      code: classifyErrorCode(error),
+      message: String(error?.message || error || "未知错误"),
+    },
+  };
+}
+
+function serializeError(error, space = 2) {
+  return `${JSON.stringify(normalizeError(error), null, space)}\n`;
+}
+
+module.exports = {
+  ERROR_SCHEMA_VERSION,
+  ERROR_RULES,
+  classifyErrorCode,
+  normalizeError,
+  serializeError,
+};

package/src/cli/flags.js

@@ -0,0 +1,9 @@
+"use strict";
+
+const HELP_FLAGS = new Set(["--help", "-h", "-help"]);
+const VERSION_FLAGS = new Set(["--version", "-v", "-version"]);
+
+module.exports = {
+  HELP_FLAGS,
+  VERSION_FLAGS,
+};

package/src/cli/help.js

@@ -0,0 +1,95 @@
+"use strict";
+
+function versionText(version) {
+  return `create-yss-spec ${version}`;
+}
+
+function helpText(version) {
+  return `create-yss-spec ${version}
+
+USAGE
+  $ create-yss-spec [COMMAND] [OPTIONS]
+
+COMMANDS
+  (default)  初始化新的模板实例仓库
+  attach     向已有项目补齐受管研发管理资产
+  sync       同步已有模板实例的受管资产
+  diff       只计算同步差异，不写入文件
+  doctor     检查模板实例、身份、Git 和安全状态
+  update     检查 npm 最新版本，如有更新则安装
+  upgrade    update 的别名
+
+OPTIONS
+  --project-name <name>              项目名称；init 不传则进入交互输入
+  --business-domain <domain>         业务领域；init 不传则进入交互输入
+  --team-size <size>                 团队规模；init 不传则可留空，默认「待补充」
+  --target-dir <dir>                 目标目录；init 不传则进入交互输入，sync/diff/doctor 默认为当前目录
+  --issue-tracker github|gitlab      默认 issue tracker 偏好（默认 github）
+  --dry-run                          兼容预演模式，不写入文件
+  --plan                             sync：输出结构化文本计划，不写入文件
+  --json                             sync/diff/doctor：输出机器可读 JSON，不写入文件
+  --apply                            attach 确认执行写入；不能与 --dry-run 同时使用
+  --force                            init：允许清空非空目录后重新生成
+                                     attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
+                                     update：即使已是最新时仍重新安装；npx / 源码目录仍不覆盖
+  --git-init                         初始化完成后执行 git init
+  --include-example-docs             显式保留示例文档（默认开启）
+  --no-example-docs                  不生成示例文档
+  -h, --help                         显示本帮助信息
+  -v, --version                      显示 CLI 版本
+
+EXAMPLES
+  $ npm create yss-spec@latest
+  $ npx create-yss-spec@latest --help
+  $ npx create-yss-spec@latest --version
+  $ npx create-yss-spec@latest \\
+      --project-name "Acme Spec Repo" \\
+      --business-domain "Investment Research" \\
+      --team-size "12" \\
+      --target-dir "./acme-spec-repo" \\
+      --issue-tracker github \\
+      --git-init
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --dry-run
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --apply
+  $ npx create-yss-spec@latest sync
+  $ npx create-yss-spec@latest sync --dry-run
+  $ npx create-yss-spec@latest sync --plan
+  $ npx create-yss-spec@latest sync --json
+  $ npx create-yss-spec@latest diff
+  $ npx create-yss-spec@latest diff --json
+  $ npx create-yss-spec@latest doctor
+  $ npx create-yss-spec@latest doctor --json
+  $ npx create-yss-spec@latest sync --target-dir . --force
+  $ npx create-yss-spec update
+  $ npx create-yss-spec update --dry-run
+  $ npx create-yss-spec upgrade
+
+LEARN MORE
+  仓库 README：https://github.com/iloveZzz/create-yss-spec#readme
+  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md
+  模板仓库：https://github.com/iloveZzz/yss-spec-project-template
+`;
+}
+
+function printVersion(version, stdout = process.stdout) {
+  stdout.write(`${versionText(version)}\n`);
+}
+
+function printHelp(version, stdout = process.stdout) {
+  stdout.write(`${helpText(version)}\n`);
+}
+
+module.exports = {
+  versionText,
+  helpText,
+  printVersion,
+  printHelp,
+};

package/src/cli/index.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const path = require("node:path");
+const packageManifest = require("../../package.json");
+const instanceRuntime = require("../template/instance-runtime");
+const {
+  decorateMetadataOwnership,
+} = require("../template/ownership-metadata");
+const {
+  decorateMetadataLifecycle,
+} = require("../template/lifecycle-metadata");
+
+// Composition-root decorator: all CLI metadata writes persist ownership and
+// lifecycle-policy baselines without duplicating cross-cutting concerns in
+// init/attach/sync command implementations.
+const writeTemplateMetadataBase = instanceRuntime.writeTemplateMetadata;
+instanceRuntime.writeTemplateMetadata = function writePolicyAwareTemplateMetadata(
+  targetDir,
+  metadata,
+  transaction = null,
+) {
+  const ownershipAware = decorateMetadataOwnership(metadata);
+  const lifecycleAware = decorateMetadataLifecycle(ownershipAware);
+  return writeTemplateMetadataBase(targetDir, lifecycleAware, transaction);
+};
+
+const { projectDoctor } = require("../api/project-doctor");
+const { runAttach } = require("../commands/attach");
+const { runDiff } = require("../commands/diff");
+const { renderDoctorText } = require("../commands/doctor");
+const { runInit } = require("../commands/init");
+const { runSync } = require("../commands/sync");
+const { runUpdateCommand } = require("../commands/update");
+const { parseArgs } = require("./args");
+const { printHelp, printVersion } = require("./help");
+const { resolveCommand } = require("./router");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "../..");
+
+async function runCli(argv = []) {
+  const route = resolveCommand(argv);
+
+  if (route.command === "help") {
+    printHelp(packageManifest.version);
+    return;
+  }
+  if (route.command === "version") {
+    printVersion(packageManifest.version);
+    return;
+  }
+  if (route.command === "update") {
+    return runUpdateCommand(route.args, {
+      packageRoot: PACKAGE_ROOT,
+      currentVersion: packageManifest.version,
+    });
+  }
+  if (route.command === "attach") {
+    return runAttach(route.args);
+  }
+  if (route.command === "sync") {
+    return runSync(route.args);
+  }
+  if (route.command === "doctor") {
+    const options = parseArgs(route.args);
+    const report = projectDoctor({ targetDir: options.targetDir || "." });
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      process.stdout.write(renderDoctorText(report));
+    }
+    return report;
+  }
+  if (route.command === "diff") {
+    return runDiff(route.args);
+  }
+
+  return runInit(route.args);
+}
+
+module.exports = {
+  runCli,
+};

package/src/cli/plan-output.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const { normalizePlan } = require("../template/plan-schema");
+
+function ownershipSuffix(item) {
+  return item.ownership ? ` [${item.ownership}]` : "";
+}
+
+function lifecycleSuffix(item) {
+  const parts = [];
+  if (item.mergeStrategy) parts.push(`merge=${item.mergeStrategy}`);
+  if (item.generatorId) {
+    parts.push(
+      `generator=${item.generatorId}@${item.generatorVersion || "?"}`,
+    );
+  }
+  return parts.length > 0 ? ` [${parts.join(",")}]` : "";
+}
+
+function renderPlanText(input) {
+  const plan = normalizePlan(input);
+  const lines = [
+    `${plan.operation} plan`,
+    `目标目录：${plan.targetDir || "-"}`,
+    `模板版本：${plan.template?.from || "unknown"} -> ${plan.template?.to || "unknown"}`,
+    `blocked: ${plan.blocked ? "yes" : "no"}`,
+  ];
+
+  for (const change of plan.changes) {
+    lines.push(
+      `${change.action}: ${change.path}${ownershipSuffix(change)}${lifecycleSuffix(change)}`,
+    );
+  }
+  for (const conflict of plan.conflicts) {
+    const forceable = conflict.forceable ? " [forceable]" : "";
+    lines.push(
+      `conflict${forceable}: ${conflict.path}${ownershipSuffix(conflict)}${lifecycleSuffix(conflict)} (${conflict.reason})`,
+    );
+  }
+  for (const unsafe of plan.unsafe) {
+    lines.push(
+      `unsafe: ${unsafe.path}${ownershipSuffix(unsafe)}${lifecycleSuffix(unsafe)} (${unsafe.reason})`,
+    );
+  }
+  for (const warning of plan.warnings) {
+    lines.push(`warning: ${warning}`);
+  }
+
+  const stats = Object.entries(plan.stats || {});
+  if (stats.length > 0) {
+    lines.push(`统计：${stats.map(([key, value]) => `${key}=${value}`).join("，")}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+module.exports = {
+  ownershipSuffix,
+  lifecycleSuffix,
+  renderPlanText,
+};

package/src/cli/prompts.js

@@ -0,0 +1,91 @@
+"use strict";
+
+const readline = require("node:readline/promises");
+
+function normalizeInteractiveOptions(options, values) {
+  return {
+    ...values,
+    issueTracker: options.issueTracker || "github",
+    dryRun: Boolean(options.dryRun),
+    force: Boolean(options.force),
+    gitInit: Boolean(options.gitInit),
+    includeExampleDocs:
+      options.includeExampleDocs === undefined
+        ? true
+        : Boolean(options.includeExampleDocs),
+  };
+}
+
+async function promptForMissingOptions(options, deps = {}) {
+  const stdin = deps.stdin || process.stdin;
+  const stdout = deps.stdout || process.stdout;
+
+  if (!stdin.isTTY) {
+    return promptFromBufferedInput(options, { stdin, stdout });
+  }
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout,
+  });
+
+  try {
+    const projectName =
+      options.projectName || (await rl.question("项目名称: ")).trim();
+    const businessDomain =
+      options.businessDomain || (await rl.question("业务领域: ")).trim();
+    const teamSizeInput =
+      options.teamSize !== undefined
+        ? options.teamSize
+        : await rl.question("团队规模（可留空）: ");
+    const targetDir =
+      options.targetDir || (await rl.question("目标目录: ")).trim();
+
+    return normalizeInteractiveOptions(options, {
+      projectName,
+      businessDomain,
+      teamSize: (teamSizeInput || "").trim() || "待补充",
+      targetDir,
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptFromBufferedInput(options, deps = {}) {
+  const stdin = deps.stdin || process.stdin;
+  const stdout = deps.stdout || process.stdout;
+  const chunks = [];
+
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+
+  const answers = Buffer.concat(chunks).toString("utf8").split(/\r?\n/);
+  let answerIndex = 0;
+  const ask = (label) => {
+    stdout.write(`${label}: `);
+    const value = answers[answerIndex] ?? "";
+    answerIndex += 1;
+    return value.trim();
+  };
+
+  const projectName = options.projectName || ask("项目名称");
+  const businessDomain = options.businessDomain || ask("业务领域");
+  const teamSizeInput =
+    options.teamSize !== undefined ? options.teamSize : ask("团队规模（可留空）");
+  const targetDir = options.targetDir || ask("目标目录");
+
+  return normalizeInteractiveOptions(options, {
+    projectName,
+    businessDomain,
+    teamSize: teamSizeInput || "待补充",
+    targetDir,
+  });
+}
+
+module.exports = {
+  normalizeInteractiveOptions,
+  promptForMissingOptions,
+  promptFromBufferedInput,
+};

package/src/cli/router.js

@@ -0,0 +1,41 @@
+"use strict";
+
+const { UPDATE_COMMANDS } = require("../self-update");
+const { HELP_FLAGS, VERSION_FLAGS } = require("./flags");
+
+function argvIncludesFlag(argv, flags) {
+  return argv.some((arg) => flags.has(arg));
+}
+
+function resolveCommand(argv = []) {
+  if (argvIncludesFlag(argv, HELP_FLAGS)) {
+    return { command: "help", args: [] };
+  }
+  if (argvIncludesFlag(argv, VERSION_FLAGS)) {
+    return { command: "version", args: [] };
+  }
+
+  const [head, ...rest] = argv;
+  if (head === "sync") {
+    return { command: "sync", args: rest };
+  }
+  if (head === "attach") {
+    return { command: "attach", args: rest };
+  }
+  if (head === "doctor") {
+    return { command: "doctor", args: rest };
+  }
+  if (head === "diff") {
+    return { command: "diff", args: rest };
+  }
+  if (UPDATE_COMMANDS.has(head)) {
+    return { command: "update", alias: head, args: rest };
+  }
+
+  return { command: "init", args: argv };
+}
+
+module.exports = {
+  argvIncludesFlag,
+  resolveCommand,
+};