@lingfan-engine/create 0.3.4 → 0.3.5

package/bin/create.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/create",
-  "version": "0.3.4",
+  "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,40 +1,29 @@
 /**
  * 命令行入口。
  *
- * 分工：参数解析与流程编排在这里，「问什么」在 `prompts.ts`，「生成什么」在
- * `generate` 域，「版本从哪来」在 `registry` 域。本文件只负责把这些串起来，
+ * 分工：参数解析与流程编排在这里，「答案怎么合成」在 `answers.ts`，「问答怎么问」
+ * 在 `prompts.ts`，「生成怎么做」在 `stage.ts`。本文件只负责把这四段串成一次运行，
  * 并把失败转成人能读的提示与退出码——库代码一律抛异常，只有这里决定措辞。
+ *
+ * 三个问题的顺序（工程名 → 描述 → 形态）由 `answers.ts` 保证，本文件不介入。
  */
 import { resolve as resolvePath } from "node:path";
-import { currentPackageManager, defaultCreateTexts } from "../shared/index.ts";
-import { isValidProjectName, suggestProjectName } from "../shared/index.ts";
+import { defaultCreateTexts } 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 {
-  askExisting,
-  askOption,
-  askProjectName,
-  createTerminalIo,
-  type PromptTexts,
-} from "./prompts.ts";
-import { installProject, renderNextSteps } from "./install.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;
@@ -60,6 +49,7 @@ class ArgError extends Error {}
  */
 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;
@@ -83,6 +73,9 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
       return next;
     };
     switch (flag) {
+      case "--description":
+        description = takeValue();
+        break;
       case "--template":
         template = takeValue();
         break;
@@ -129,6 +122,7 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
   }
   return {
     projectName,
+    description,
     template,
     framework,
     shell,
@@ -179,96 +173,44 @@ 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 preset = resolvePreset(args.template, meta);
-    if (preset === undefined) return 1;
-    const framework = await resolveOption(
-      "framework",
-      args.framework ?? preset.framework,
-      meta,
-      promptTexts,
-      io,
-    );
-    if (framework === undefined) return 1;
-    const shell = await resolveOption(
-      "shell",
-      args.shell ?? preset.shell,
+    const answers = await resolveAnswers({
+      args,
       meta,
-      promptTexts,
+      templateRoot,
       io,
-    );
-    if (shell === undefined) return 1;
-    // 故事源不再提问：骨架自带整条 TS 创作链，它就是缺省形态。要手写 `.story`
-    // 的人在命令行给 `--sources story` 或用 `--template` 带上第三段即可。
-    const sources = args.sources ?? preset.sources ?? "ts";
-    if (!meta.sources.some((option) => option.id === sources)) {
-      process.stderr.write(`${texts.sourcesUnknown}：${sources}\n`);
-      return 1;
-    }
+      texts,
+    });
+    if (answers === undefined) return 1;
     const existing = await resolveExisting({
       args,
-      projectName,
+      projectName: answers.projectName,
       io,
-      texts: promptTexts,
+      texts,
     });
     if (existing === undefined) return 1;
-    return await generate({
-      args,
+    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();
   }
 }
 
-/**
- * 解析 `--template`：写作 `框架[-壳[-故事源]]`。
- *
- * 只做切分，合法性交给调用方——它已经要按模板声明校验一遍，这里再判一次
- * 会得到两套口径，日后加形态容易漏改其一。
- */
-function resolvePreset(
-  template: string | undefined,
-  meta: TemplateMeta,
-): { framework?: string; shell?: string; sources?: string } | undefined {
-  if (template === undefined) return {};
-  const parts = template.split("-").filter((part) => part !== "");
-  if (parts.length === 0 || parts.length > 3) {
-    process.stderr.write(
-      `${defaultCreateTexts.templateMalformed}：${template}\n`,
-    );
-    return undefined;
-  }
-  const [framework, shell, sources] = parts;
-  const known = (options: readonly { id: string }[], id: string): boolean =>
-    options.some((option) => option.id === id);
-  if (!known(meta.frameworks, framework)) {
-    process.stderr.write(
-      `${defaultCreateTexts.frameworkUnknown}：${framework}\n`,
-    );
-    return undefined;
-  }
-  if (shell !== undefined && !known(meta.shells, shell)) {
-    process.stderr.write(`${defaultCreateTexts.shellUnknown}：${shell}\n`);
-    return undefined;
-  }
-  if (sources !== undefined && !known(meta.sources, sources)) {
-    process.stderr.write(`${defaultCreateTexts.sourcesUnknown}：${sources}\n`);
-    return undefined;
-  }
-  return { framework, shell, sources };
-}
-
 /**
  * 决定目标目录非空时怎么处置。
  *
@@ -298,126 +240,3 @@ async function resolveExisting(input: {
   }
   return picked;
 }
-
-/** 生成一步：查版本 → 写文件 → 可选安装 → 打印后续步骤 */
-async function generate(input: {
-  readonly args: CreateArgs;
-  readonly meta: TemplateMeta;
-  readonly templateRoot: string;
-  readonly projectName: string;
-  readonly framework: string;
-  readonly shell: string;
-  readonly sources: string;
-  readonly existing: ExistingTarget;
-}): Promise<number> {
-  const texts = defaultCreateTexts;
-  const manager = currentPackageManager();
-  const targetBase = resolvePath(input.args.dir ?? process.cwd());
-  const layout = {
-    templateRoot: input.templateRoot,
-    targetBase,
-    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, existing: input.existing, 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 installProject(result.projectDir, manager);
-    if (!installed) process.stderr.write(`${texts.warnInstallFailed}\n`);
-  }
-
-  process.stdout.write(
-    [
-      "",
-      `${texts.doneTitle}：${result.projectDir}`,
-      `共 ${result.fileCount} 个文件，框架 ${result.framework}，壳 ${result.shell}，故事源 ${result.sources}`,
-      "",
-      installed ? "依赖已安装。" : "依赖未安装。",
-      renderNextSteps(result.projectDir, manager, texts),
-      "",
-    ].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`);
-    return undefined;
-  }
-  if (io === undefined) {
-    return suggestProjectName("");
-  }
-  return await askProjectName(io, texts, undefined);
-}
-
-/**
- * 解析框架/壳：值必须在模板声明的表里。
- *
- * 表是唯一事实来源——元数据没声明的形态，叠加层目录未必存在，放过去会生成出
- * 静默缺文件的工程。故事源不在这里判：它只剩「作者手写 `.story`」这一种偏离，
- * 由调用方按同一张表查一次即可。
- */
-async function resolveOption(
-  kind: "framework" | "shell",
-  value: string | undefined,
-  meta: TemplateMeta,
-  texts: PromptTexts,
-  io: Parameters<typeof askOption>[0] | undefined,
-): Promise<string | undefined> {
-  const options = kind === "framework" ? meta.frameworks : meta.shells;
-  const invalidText =
-    kind === "framework" ? texts.frameworkUnknown : texts.shellUnknown;
-  const label =
-    kind === "framework" ? texts.promptFramework : texts.promptShell;
-  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`);
-    return undefined;
-  }
-  return picked;
-}
-
-/** 把异常折成一行提示：只暴露信息，不暴露堆栈 */
-function describe(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/cli/index.ts

@@ -1,19 +1,27 @@
 /**
  * CLI 域唯一出口。
  *
- * 只做转发：参数解析（`cli.ts`）、交互问答（`prompts.ts`）、依赖安装与后续命令
- * 渲染（`install.ts`）三层各自成文件，调用方从这里进出，不穿过文件名。
+ * 只做转发：参数解析（`cli.ts`）、答案合成（`answers.ts`）、交互问答（`prompts.ts`）、
+ * 生成编排（`stage.ts`）、依赖安装与后续命令渲染（`install.ts`）各自成文件，
+ * 调用方从这里进出，不穿过文件名。
  */
 export { parseArgs, runCreateCli } from "./cli.ts";
 export type { CreateArgs } from "./cli.ts";
+export { resolveAnswers } from "./answers.ts";
+export type { AnswerSources, AnswerTexts, CreateAnswers } from "./answers.ts";
 export {
+  askDescription,
   askExisting,
-  askOption,
+  askLayers,
   askProjectName,
   createTerminalIo,
+  findLayerConflicts,
+  parseLayerAnswer,
   pickOption,
 } from "./prompts.ts";
 export type { PromptIo, PromptTexts } from "./prompts.ts";
+export { runStage } from "./stage.ts";
+export type { StageOptions } from "./stage.ts";
 export {
   fillManagerCommands,
   installProject,