@lingfan-engine/create 0.3.3 → 0.3.5

package/bin/create.mjs

@@ -8,11 +8,15 @@
  * `src/cli/cli.ts`，也不该被迫装一整套构建链。垫片用本包自带依赖 `tsx` 装载真实 CLI，
  * 呈现与编排逻辑仍然只有一份。
  *
- * 用法：`npm create @lingfan-engine [工程名] [-- --framework vue --shell browser]`；
- * 不带参数即进入交互问答。
+ * 用法：`npm create @lingfan-engine [工程名] [选项]`。不带参数即进入交互问答，
+ * 依次问工程名、描述与形态；形态是一次多选，可叠加的层由模板元数据的互斥声明
+ * 决定哪些组合合法。
+ *
+ * `--template <id>` 是旧的分维写法替代品，只在脚本用法（CI 里用参数跳过问答）
+ * 场景出现，帮助里列在末段。
  */
 import { tsImport } from "tsx/esm/api";
 
-const { runCreateCli } = await tsImport("../src/cli/cli.ts", import.meta.url);
+const { runCreateCli } = await tsImport("../src/cli/index.ts", import.meta.url);
 const code = await runCreateCli(process.argv.slice(2));
 if (code !== 0) process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/create",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "工程生成器：从模板骨架生成新工程，可选框架与壳",
   "license": "Apache-2.0",

package/src/cli/answers.ts

@@ -0,0 +1,275 @@
+/**
+ * 三个问题的答案合成。
+ *
+ * 为什么要独立成文件：答案不是「问一遍」的结果，而是三处来源按固定优先级叠出来的
+ * ——命令行参数 > 交互问答 > 模板缺省。三者的优先级、跳过的时机、非交互终端怎么
+ * 收场，都是同一件事的不同侧面，散在流程里就会各自漂移。
+ *
+ * 顺序固定为 工程名 → 描述 → 形态，且**已给出的项跳过、剩余项保持原顺序**：
+ * 名字决定目录与包名，描述与形态是「这个工程」之上的补充；把顺序交给问答脚本，
+ * 使用者就得跟着脚本的节奏改口。
+ *
+ * 形态用一次多选而不是三次单选：可叠加的层是一张网（选 Vue 就排除小程序，桌面壳
+ * 又与小程序互斥），逐维度问会把矛盾留到最后才暴露。
+ */
+import {
+  isValidProjectName,
+  normalizeDescription,
+  suggestProjectName,
+} from "../shared/index.ts";
+import {
+  selectableLayers,
+  type TemplateMeta,
+  type TemplateOption,
+} from "../registry/index.ts";
+import {
+  askDescription,
+  askLayers,
+  askProjectName,
+  type PromptIo,
+  type PromptTexts,
+} from "./prompts.ts";
+
+/** 合成答案所需的参数面：只认本文件要用的字段，不依赖命令行类型 */
+export interface AnswerSources {
+  readonly projectName?: string;
+  readonly description?: string;
+  readonly template?: string;
+  readonly framework?: string;
+  readonly shell?: string;
+  readonly sources?: string;
+  /** 全部取缺省、一个问题都不问 */
+  readonly yes: boolean;
+}
+
+/**
+ * 一次生成所需的全部答案。
+ *
+ * `description` 用空串表示「没有描述」：清单里因此不出现 `description` 键，
+ * 而不是出现一个空字符串——两者在工具链里的语义不同，空串会被显示成一句空话。
+ */
+export interface CreateAnswers {
+  readonly projectName: string;
+  readonly description: string;
+  readonly framework: string;
+  readonly shell: string;
+  readonly sources: string;
+}
+
+/** 合成答案需要的文案：问答提示语加上参数校验的失败措辞 */
+export interface AnswerTexts extends PromptTexts {
+  readonly frameworkUnknown: string;
+  readonly shellUnknown: string;
+  readonly sourcesUnknown: string;
+  readonly templateMalformed: string;
+}
+
+/**
+ * 按「参数 > 交互 > 缺省」合成答案；需要问却问不了时返回 undefined。
+ *
+ * 返回 undefined 的两种情形都已在这里把原因写给使用者：参数不合法（形态写法、
+ * 未知层 id），以及非交互终端下仍有未指定的项。调用方只需把 undefined 转成
+ * 退出码 1，不必重复判定。
+ */
+export async function resolveAnswers(input: {
+  readonly args: AnswerSources;
+  readonly meta: TemplateMeta;
+  readonly templateRoot: string;
+  readonly io: PromptIo | undefined;
+  readonly texts: AnswerTexts;
+}): Promise<CreateAnswers | undefined> {
+  const { args, meta, texts } = input;
+  // 形态先算：`--template` 写错时应当立刻失败，而不是先问完名字再告诉你写法不对。
+  const preset = resolvePreset(input.args.template, meta, texts);
+  if (preset === undefined) return undefined;
+  const formGiven =
+    args.template !== undefined ||
+    args.framework !== undefined ||
+    args.shell !== undefined ||
+    args.sources !== undefined;
+
+  const pending: string[] = [];
+  if (args.projectName === undefined) pending.push(texts.promptProjectName);
+  if (args.description === undefined) pending.push(texts.promptDescription);
+  if (!formGiven) pending.push(texts.promptLayers);
+  if (pending.length > 0 && input.io === undefined && !args.yes) {
+    process.stderr.write(
+      `${texts.nonInteractive}：${pending.join("、")}\n${texts.nonInteractiveHint}\n`,
+    );
+    return undefined;
+  }
+
+  const projectName = await resolveName(args, texts, input.io);
+  if (projectName === undefined) return undefined;
+  const description = await resolveDescription(args, texts, input.io);
+
+  const form = formGiven
+    ? resolvePinnedForm(args, preset, meta, texts)
+    : await resolvePickedForm(input.templateRoot, meta, texts, input.io);
+  if (form === undefined) return undefined;
+
+  return { projectName, description, ...form };
+}
+
+/**
+ * 工程名：参数优先且必须合法；参数缺席时取建议值，交互模式则问一次（打错重问）。
+ *
+ * 参数非法直接失败而不是退回问答：脚本里给了名字又给错，说明它预期这个名字生效，
+ * 悄悄换一个名字生成出去比报错更糟。
+ */
+async function resolveName(
+  args: AnswerSources,
+  texts: AnswerTexts,
+  io: PromptIo | undefined,
+): Promise<string | undefined> {
+  if (args.projectName !== undefined) {
+    if (isValidProjectName(args.projectName)) return args.projectName;
+    process.stderr.write(`${texts.nameInvalid}：${args.projectName}\n`);
+    return undefined;
+  }
+  if (io === undefined) return suggestProjectName("");
+  return await askProjectName(io, texts, undefined);
+}
+
+/**
+ * 描述：参数优先，缺席则问一次；两处都按同一套归一处理。
+ *
+ * 参数给的描述也截断到上限：否则 `--description` 与交互输入的同一段文字会得到
+ * 不同结果，而它们最终写进同一份清单。
+ */
+async function resolveDescription(
+  args: AnswerSources,
+  texts: AnswerTexts,
+  io: PromptIo | undefined,
+): Promise<string> {
+  if (args.description !== undefined) {
+    return normalizeDescription(args.description);
+  }
+  if (io === undefined) return "";
+  return await askDescription(io, texts);
+}
+
+/**
+ * 形态已由参数指定时的三维落位。
+ *
+ * 走的是「三维直接指定」的旧口头契约：任一维度缺席就取该维度首项，且**不做互斥
+ * 校验**——调用方是脚本，它自己拼出来的组合要么本来合法，要么是在刻意生成异常
+ * 样本。互斥校验只服务于问答，因为只有人会一次选到互相排斥的两层。
+ */
+function resolvePinnedForm(
+  args: AnswerSources,
+  preset: Preset,
+  meta: TemplateMeta,
+  texts: AnswerTexts,
+): { framework: string; shell: string; sources: string } | undefined {
+  const framework = pickKnown(
+    args.framework ?? preset.framework,
+    meta.frameworks,
+    texts.frameworkUnknown,
+  );
+  if (framework === undefined) return undefined;
+  const shell = pickKnown(
+    args.shell ?? preset.shell,
+    meta.shells,
+    texts.shellUnknown,
+  );
+  if (shell === undefined) return undefined;
+  const sources = pickKnown(
+    args.sources ?? preset.sources,
+    meta.sources,
+    texts.sourcesUnknown,
+  );
+  if (sources === undefined) return undefined;
+  return { framework, shell, sources };
+}
+
+/**
+ * 形态靠问答决定时的三维落位：没选中该维度就取其首项。
+ *
+ * 判「可以选哪些层」用目录存在性而非 id 白名单：缺省层（`none`/`browser`/`ts`）
+ * 没有目录，因此不出现在选项面，只作为「这一维没选」的落点。
+ */
+async function resolvePickedForm(
+  templateRoot: string,
+  meta: TemplateMeta,
+  texts: AnswerTexts,
+  io: PromptIo | undefined,
+): Promise<{ framework: string; shell: string; sources: string } | undefined> {
+  const layers = selectableLayers(templateRoot, meta);
+  const picked =
+    io === undefined ? [] : await askLayers(io, texts, layers, layers);
+  const firstOf = (
+    list: readonly TemplateOption[],
+    invalidText: string,
+  ): string | undefined => {
+    const hit = list.find((option) => picked.includes(option.id)) ?? list[0];
+    if (hit === undefined) {
+      process.stderr.write(`${invalidText}\n`);
+      return undefined;
+    }
+    return hit.id;
+  };
+  const framework = firstOf(meta.frameworks, texts.frameworkUnknown);
+  if (framework === undefined) return undefined;
+  const shell = firstOf(meta.shells, texts.shellUnknown);
+  if (shell === undefined) return undefined;
+  const sources = firstOf(meta.sources, texts.sourcesUnknown);
+  if (sources === undefined) return undefined;
+  return { framework, shell, sources };
+}
+
+/** 从一张表里取值：缺席取首项，取到却不在表里即报错 */
+function pickKnown(
+  value: string | undefined,
+  options: readonly TemplateOption[],
+  invalidText: string,
+): string | undefined {
+  const picked = value ?? options[0]?.id;
+  if (picked !== undefined && options.some((option) => option.id === picked)) {
+    return picked;
+  }
+  process.stderr.write(`${invalidText}：${String(picked)}\n`);
+  return undefined;
+}
+
+/** `--template` 切出来的三维取值；缺席项为 undefined */
+interface Preset {
+  readonly framework?: string;
+  readonly shell?: string;
+  readonly sources?: string;
+}
+
+/**
+ * 解析 `--template`：写作 `框架[-壳[-故事源]]`。
+ *
+ * 只做切分与「id 在该维度里」的校验，不参与互斥判断：它是给旧脚本的等价写法，
+ * 语义与手工分三维给参数一致。
+ */
+function resolvePreset(
+  template: string | undefined,
+  meta: TemplateMeta,
+  texts: AnswerTexts,
+): Preset | undefined {
+  if (template === undefined) return {};
+  const parts = template.split("-").filter((part) => part !== "");
+  if (parts.length === 0 || parts.length > 3) {
+    process.stderr.write(`${texts.templateMalformed}：${template}\n`);
+    return undefined;
+  }
+  const [framework, shell, sources] = parts;
+  const known = (options: readonly TemplateOption[], id: string): boolean =>
+    options.some((option) => option.id === id);
+  if (!known(meta.frameworks, framework)) {
+    process.stderr.write(`${texts.frameworkUnknown}：${framework}\n`);
+    return undefined;
+  }
+  if (shell !== undefined && !known(meta.shells, shell)) {
+    process.stderr.write(`${texts.shellUnknown}：${shell}\n`);
+    return undefined;
+  }
+  if (sources !== undefined && !known(meta.sources, sources)) {
+    process.stderr.write(`${texts.sourcesUnknown}：${sources}\n`);
+    return undefined;
+  }
+  return { framework, shell, sources };
+}

package/src/cli/cli.ts

@@ -1,41 +1,36 @@
 /**
  * 命令行入口。
  *
- * 分工：参数解析与流程编排在这里，「问什么」在 `prompts.ts`，「生成什么」在
- * `generate` 域，「版本从哪来」在 `registry` 域。本文件只负责把这些串起来，
+ * 分工：参数解析与流程编排在这里，「答案怎么合成」在 `answers.ts`，「问答怎么问」
+ * 在 `prompts.ts`，「生成怎么做」在 `stage.ts`。本文件只负责把这四段串成一次运行，
  * 并把失败转成人能读的提示与退出码——库代码一律抛异常，只有这里决定措辞。
+ *
+ * 三个问题的顺序（工程名 → 描述 → 形态）由 `answers.ts` 保证，本文件不介入。
  */
-import { spawn } from "node:child_process";
 import { resolve as resolvePath } from "node:path";
 import { defaultCreateTexts } from "../shared/index.ts";
-import { isValidProjectName, suggestProjectName } from "../shared/index.ts";
 import {
-  layerBases,
-  generateProject,
-  collectDependencyNames,
+  isOccupied,
+  projectDirOf,
+  type ExistingTarget,
 } from "../generate/index.ts";
-import {
-  checkEngineCompatibility,
-  readTemplateMeta,
-  resolveTemplateRoot,
-  resolveVersions,
-  type TemplateMeta,
-} from "../registry/index.ts";
-import {
-  askOption,
-  askProjectName,
-  createTerminalIo,
-  type PromptTexts,
-} from "./prompts.ts";
+import { readTemplateMeta, resolveTemplateRoot } from "../registry/index.ts";
+import { resolveAnswers } from "./answers.ts";
+import { askExisting, createTerminalIo, type PromptTexts } from "./prompts.ts";
+import { runStage } from "./stage.ts";
 
 /** 解析后的命令行参数；缺席项为 undefined，交由问答或模板缺省值补 */
 export interface CreateArgs {
   readonly projectName?: string;
+  /** 工程描述；写进两份清单，空串或缺席表示不写该字段 */
+  readonly description?: string;
+  readonly template?: string;
   readonly framework?: string;
   readonly shell?: string;
   readonly sources?: string;
   readonly dir?: string;
   readonly install: boolean;
+  readonly existing?: ExistingTarget;
   readonly yes: boolean;
   readonly help: boolean;
 }
@@ -48,14 +43,20 @@ class ArgError extends Error {}
  *
  * 支持 `--flag value` 与 `--flag=value` 两种写法：前者是手敲的习惯，
  * 后者在脚本里拼接更省事，两者都认不需要额外成本。
+ *
+ * 依赖缺省**不**安装：装依赖是几十秒到几分钟的副作用，脚本里更希望它显式请求
+ * （`--install`）。旧脚本里的 `--no-install` 仍然认，等于什么都不做。
  */
 export function parseArgs(argv: readonly string[]): CreateArgs {
   let projectName: string | undefined;
+  let description: string | undefined;
+  let template: string | undefined;
   let framework: string | undefined;
   let shell: string | undefined;
   let sources: string | undefined;
   let dir: string | undefined;
-  let install = true;
+  let install = false;
+  let existing: ExistingTarget | undefined;
   let yes = false;
   let help = false;
 
@@ -72,6 +73,12 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
       return next;
     };
     switch (flag) {
+      case "--description":
+        description = takeValue();
+        break;
+      case "--template":
+        template = takeValue();
+        break;
       case "-f":
       case "--framework":
         framework = takeValue();
@@ -88,9 +95,15 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
       case "--dir":
         dir = takeValue();
         break;
+      case "--install":
+        install = true;
+        break;
       case "--no-install":
         install = false;
         break;
+      case "--overwrite":
+        existing = "clear";
+        break;
       case "-y":
       case "--yes":
         yes = true;
@@ -107,7 +120,19 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
         projectName = flag;
     }
   }
-  return { projectName, framework, shell, sources, dir, install, yes, help };
+  return {
+    projectName,
+    description,
+    template,
+    framework,
+    shell,
+    sources,
+    dir,
+    install,
+    existing,
+    yes,
+    help,
+  };
 }
 
 /** 拆出 `--flag=value`；无等号时第二项为 undefined */
@@ -148,196 +173,70 @@ export async function runCreateCli(argv: readonly string[]): Promise<number> {
   }
   const meta = readTemplateMeta(templateRoot);
 
-  const io = args.yes ? undefined : createTerminalIo();
-  const promptTexts = texts;
+  // 只有「允许提问且确实能问」时才建问答面：`--yes` 承诺一个问题都不问；
+  // 非交互终端（管道、CI、被重定向的 stdin）上没有回车可打，建出来只会挂在
+  // 等一个永远不来的输入上。没有问答面时由 `answers.ts` 判定并给出可用参数。
+  const interactive = !args.yes && process.stdin.isTTY === true;
+  const io = interactive ? createTerminalIo() : undefined;
   try {
-    const projectName = await resolveName(args, promptTexts, io);
-    if (projectName === undefined) return 1;
-    const framework = await resolveOption(
-      "framework",
-      args.framework,
-      meta,
-      promptTexts,
-      io,
-    );
-    if (framework === undefined) return 1;
-    const shell = await resolveOption(
-      "shell",
-      args.shell,
-      meta,
-      promptTexts,
-      io,
-    );
-    if (shell === undefined) return 1;
-    const sources = await resolveOption(
-      "sources",
-      args.sources,
+    const answers = await resolveAnswers({
+      args,
       meta,
-      promptTexts,
+      templateRoot,
       io,
-    );
-    if (sources === undefined) return 1;
-    return await generate({
+      texts,
+    });
+    if (answers === undefined) return 1;
+    const existing = await resolveExisting({
       args,
+      projectName: answers.projectName,
+      io,
+      texts,
+    });
+    if (existing === undefined) return 1;
+    return await runStage({
       meta,
       templateRoot,
-      projectName,
-      framework,
-      shell,
-      sources,
+      dir: args.dir,
+      projectName: answers.projectName,
+      description: answers.description,
+      framework: answers.framework,
+      shell: answers.shell,
+      sources: answers.sources,
+      existing,
+      install: args.install,
     });
   } finally {
     io?.close();
   }
 }
 
-/** 生成一步：查版本 → 写文件 → 可选安装 → 打印后续步骤 */
-async function generate(input: {
+/**
+ * 决定目标目录非空时怎么处置。
+ *
+ * 缺省是取消：覆盖别人的工程无法撤销，`--yes` 也不该替人做这个决定。
+ * `--overwrite` 是显式表态，交互模式下也会问一次。
+ */
+async function resolveExisting(input: {
   readonly args: CreateArgs;
-  readonly meta: TemplateMeta;
-  readonly templateRoot: string;
   readonly projectName: string;
-  readonly framework: string;
-  readonly shell: string;
-  readonly sources: string;
-}): Promise<number> {
-  const texts = defaultCreateTexts;
-  const targetBase = resolvePath(input.args.dir ?? process.cwd());
-  const layout = {
-    templateRoot: input.templateRoot,
-    targetBase,
+  readonly io: Parameters<typeof askExisting>[0] | undefined;
+  readonly texts: PromptTexts & { readonly targetExists: string };
+}): Promise<ExistingTarget | undefined> {
+  const projectDir = projectDirOf({
+    targetBase: resolvePath(input.args.dir ?? process.cwd()),
     projectName: input.projectName,
-    framework: input.framework,
-    shell: input.shell,
-    sources: input.sources,
-    resolved: new Map<string, string>(),
-  };
-
-  process.stderr.write(`${texts.stageResolve}\n`);
-  const names = collectDependencyNames(layerBases(layout));
-  const resolved = await resolveVersions(names);
-  if (resolved.size === 0 && names.length > 0) {
-    process.stderr.write(`${texts.warnVersionOffline}\n`);
-  }
-  // 版本判定在写盘之前：模板要求的引擎还没发布时，生成出来的工程装不上，
-  // 让它失败在「什么都没写」的时刻，而不是在别人的工程里第一次 pnpm dev 时。
-  const incompatible = checkEngineCompatibility(
-    input.meta.minEngineVersion,
-    resolved,
-  );
-  if (incompatible !== undefined) {
-    process.stderr.write(`${incompatible}\n`);
-    return 1;
-  }
-
-  process.stderr.write(`${texts.stageCopy}\n`);
-  let result;
-  try {
-    result = generateProject({ ...layout, resolved });
-  } catch (error) {
-    process.stderr.write(`${describe(error)}\n`);
-    return 1;
-  }
-
-  let installed = false;
-  if (input.args.install) {
-    process.stderr.write(`${texts.stageInstall}\n`);
-    installed = await install(result.projectDir);
-    if (!installed) process.stderr.write(`${texts.warnInstallFailed}\n`);
-  }
-
-  process.stdout.write(
-    [
-      "",
-      `${texts.doneTitle}：${result.projectDir}`,
-      `共 ${result.fileCount} 个文件，框架 ${result.framework}，壳 ${result.shell}，故事源 ${result.sources}`,
-      "",
-      installed ? "依赖已安装。" : "依赖未安装。",
-      texts.nextSteps.split("<name>").join(result.projectDir),
-      "",
-    ].join("\n"),
-  );
-  return 0;
-}
-
-/** 解析工程名：参数优先，参数非法即报错；交互模式打错会重问 */
-async function resolveName(
-  args: CreateArgs,
-  texts: PromptTexts & { readonly nameInvalid: string },
-  io: Parameters<typeof askProjectName>[0] | undefined,
-): Promise<string | undefined> {
-  if (args.projectName !== undefined) {
-    if (isValidProjectName(args.projectName)) return args.projectName;
-    process.stderr.write(`${texts.nameInvalid}：${args.projectName}\n`);
+  });
+  if (!isOccupied(projectDir)) return "cancel";
+  if (input.args.existing !== undefined) return input.args.existing;
+  if (input.io === undefined) {
+    process.stderr.write(`${input.texts.targetExists}：${projectDir}\n`);
     return undefined;
   }
-  if (io === undefined) {
-    return suggestProjectName("");
-  }
-  return await askProjectName(io, texts, undefined);
-}
-
-/**
- * 解析框架/壳/故事源：必须真实存在对应的叠加层，否则报错。
- *
- * 只校验「模板声明过」而不校验「目录存在」会放过一种情况：元数据写了 `vue`
- * 但仓库里没有 `overlays/vue`，生成出来的工程静默缺少该框架的文件。
- */
-async function resolveOption(
-  kind: "framework" | "shell" | "sources",
-  value: string | undefined,
-  meta: TemplateMeta,
-  texts: PromptTexts & { readonly overlayMissing: string },
-  io: Parameters<typeof askOption>[0] | undefined,
-): Promise<string | undefined> {
-  const options =
-    kind === "framework"
-      ? meta.frameworks
-      : kind === "shell"
-        ? meta.shells
-        : meta.sources;
-  const invalidText =
-    kind === "framework"
-      ? texts.frameworkUnknown
-      : kind === "shell"
-        ? texts.shellUnknown
-        : texts.sourcesUnknown;
-  const label =
-    kind === "framework"
-      ? texts.promptFramework
-      : kind === "shell"
-        ? texts.promptShell
-        : texts.promptSources;
-  const picked =
-    value !== undefined || io === undefined
-      ? (value ?? options[0]?.id)
-      : await askOption(io, label, options, undefined, invalidText);
-  if (picked === undefined || !options.some((item) => item.id === picked)) {
-    process.stderr.write(`${invalidText}：${String(picked)}\n`);
+  const picked = await askExisting(input.io, input.texts);
+  if (picked === "cancel") {
+    process.stderr.write(`${input.texts.targetExists}：${projectDir}\n`);
     return undefined;
   }
   return picked;
 }
-
-/**
- * 在工程目录里装依赖。
- *
- * 只有 pnpm：本仓与模板的工程都以 pnpm 为准（锁文件、workspace 协议改写都依赖它），
- * 换别的包管理器会生成第二份锁文件，日后发布还要再处理一遍。
- */
-async function install(dir: string): Promise<boolean> {
-  return await new Promise<boolean>((done) => {
-    const child = spawn("pnpm", ["install"], {
-      cwd: dir,
-      stdio: "inherit",
-      shell: process.platform === "win32",
-    });
-    child.on("error", () => done(false));
-    child.on("close", (code) => done(code === 0));
-  });
-}
-
-/** 把异常折成一行提示：只暴露信息，不暴露堆栈 */
-function describe(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}