@lingfan-engine/create 0.3.3 → 0.3.5

package/src/cli/index.ts

@@ -0,0 +1,29 @@
+/**
+ * CLI 域唯一出口。
+ *
+ * 只做转发：参数解析（`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,
+  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,
+  renderNextSteps,
+} from "./install.ts";

package/src/cli/install.ts

@@ -0,0 +1,60 @@
+/**
+ * 生成之后的两个副作用：装依赖、打印下一步。
+ *
+ * 为什么单独成文件：这两件事都要按调用方的包管理器变写法，而组合编排
+ * （`cli.ts`）不该关心命令怎么拼。生成器是给**别人**用的工具，本仓开发固定
+ * pnpm 是仓库约定，不是产物约定——`npm create` 起的进程就该看到 npm 的命令。
+ */
+import { spawn } from "node:child_process";
+import type { CreateTexts, PackageManager } from "../shared/index.ts";
+
+/**
+ * 在生成的工程里装依赖。
+ *
+ * 命令与可执行名都取自 `manager`：装了 npm 的人未必装了 pnpm，反过来也一样，
+ * 猜错就是一句「找不到命令」。`shell` 在 Windows 上是必需的——npm 与 pnpm 的
+ * 可执行是 `.cmd`，不带 shell 直接 spawn 会 ENOENT。
+ */
+export async function installProject(
+  dir: string,
+  manager: PackageManager,
+): Promise<boolean> {
+  return await new Promise<boolean>((done) => {
+    const child = spawn(manager.id, [manager.install], {
+      cwd: dir,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => done(false));
+    child.on("close", (code) => done(code === 0));
+  });
+}
+
+/**
+ * 把文案里的 `<install>` / `<dev>` 换成该包管理器的实际写法。
+ *
+ * 生成后的提示若写死 `pnpm install`，用 npm 的人第一步就会撞上「没有这个命令」
+ * ——这类提示写错比不写更糟，因为它看起来像官方指引。
+ */
+export function fillManagerCommands(
+  text: string,
+  manager: PackageManager,
+): string {
+  return text
+    .split("<install>")
+    .join(`${manager.id} ${manager.install}`)
+    .split("<dev>")
+    .join(`${manager.id} ${manager.script}`);
+}
+
+/** 生成后的三步提示：`cd` 到工程目录、装依赖、跑起来 */
+export function renderNextSteps(
+  projectDir: string,
+  manager: PackageManager,
+  texts: CreateTexts,
+): string {
+  return fillManagerCommands(
+    texts.nextSteps.split("<name>").join(projectDir),
+    manager,
+  );
+}

package/src/cli/prompts.ts

@@ -1,28 +1,49 @@
 /**
  * 交互问答。
  *
- * 生成器要问四件事：工程名、框架、壳、故事源形态。四项都能用命令行参数预先给定——CI、
- * 脚本、或「我已经知道要什么」的人不该被问答拦住，因此问答只在参数缺席时发生。
+ * 生成器按固定顺序问三件事：工程名 → 描述 → 形态。顺序不能换：工程名决定目录与
+ * 包名，描述与形态都是在「这个工程」之上的补充；先问后者再问名字，人得回头改口。
+ *
+ * 形态是**一次多选**而不是三个单选：可叠加的层是一张网，不是三根互不相干的轴——
+ * 选 Vue 就排除了小程序，选桌面壳又与小程序互斥。逐个维度问会把矛盾留到最后才
+ * 暴露，一次问清则当场说穿重问。
+ *
+ * 目标目录非空时另问一次怎么处置：那是覆盖别人的东西，必须由使用者当场表态，
+ * 不能拿缺省值糊过去（缺省是取消）。
  *
  * 实现只用 `node:readline` 的 promise 版：它随 Node 自带，不引第三方交互库。
- * 提问写 stderr 而不是 stdout，产物路径之类的结果才走 stdout，这样
- * `npm create … > log.txt` 不会把问题一起吞掉。
+ * 提问写 stderr 而不是 stdout，这样 `npm create … > log.txt` 不会把问题一起吞掉。
  */
 import { createInterface } from "node:readline/promises";
-import { isValidProjectName, suggestProjectName } from "../shared/index.ts";
-import type { TemplateOption } from "../registry/index.ts";
+import {
+  isValidProjectName,
+  normalizeDescription,
+  suggestProjectName,
+} from "../shared/index.ts";
+import type { LayerConflict, TemplateOption } from "../registry/index.ts";
+import type { ExistingTarget } from "../generate/index.ts";
 
 /** 问答需要的一份文案；由调用方从共享文案表传入，便于测试替换 */
 export interface PromptTexts {
   readonly promptProjectName: string;
-  readonly promptFramework: string;
-  readonly promptShell: string;
-  readonly promptSources: string;
+  readonly promptDescription: string;
+  readonly descriptionHint: string;
+  readonly promptLayers: string;
+  readonly nonInteractive: string;
+  readonly nonInteractiveHint: string;
+  readonly promptExisting: string;
   readonly nameRequired: string;
   readonly nameInvalid: string;
-  readonly frameworkUnknown: string;
-  readonly shellUnknown: string;
-  readonly sourcesUnknown: string;
+  readonly layersEmptyHint: string;
+  readonly layersInvalid: string;
+  readonly layersConflict: string;
+  readonly layersConflictHint: string;
+  readonly existingIgnore: string;
+  readonly existingIgnoreHint: string;
+  readonly existingClear: string;
+  readonly existingClearHint: string;
+  readonly existingCancel: string;
+  readonly existingCancelHint: string;
 }
 
 /** 问答依赖的输入输出面；默认接真实终端，测试可换成脚本化实现 */
@@ -31,15 +52,48 @@ export interface PromptIo {
   close(): void;
 }
 
-/** 造一个接到标准输入输出的问答面 */
-export function createTerminalIo(): PromptIo {
+/** 输入已关闭时的失败信息：调用方会把它印出来并退出，因此要人读得懂 */
+const INPUT_CLOSED = "标准输入已关闭，无法继续问答";
+
+/**
+ * 造一个接到标准输入输出的问答面。
+ *
+ * 参数是为了可测：非交互终端下 `question()` 必须失败而不是永远挂着。`readline` 在
+ * 输入流结束后只会发一个 `close` 事件，它自己的 promise 因此既不 resolve 也不
+ * reject——进程于是停在「等一个永远不会到的回车」，靠外部超时才退出。这里把
+ * `close` 转成 reject，让失败变成一次可捕获的异常。
+ */
+export function createTerminalIo(
+  input: NodeJS.ReadableStream = process.stdin,
+  output: NodeJS.WritableStream = process.stderr,
+): PromptIo {
   const rl = createInterface({
-    input: process.stdin,
-    output: process.stderr,
-    terminal: process.stdin.isTTY === true,
+    input,
+    output,
+    terminal: input === process.stdin && process.stdin.isTTY === true,
+  });
+  let closed = false;
+  rl.once("close", () => {
+    closed = true;
   });
   return {
-    question: (text) => rl.question(text),
+    question: (text) => {
+      if (closed) return Promise.reject(new Error(INPUT_CLOSED));
+      return new Promise<string>((resolve, reject) => {
+        const fail = (): void => reject(new Error(INPUT_CLOSED));
+        rl.once("close", fail);
+        rl.question(text).then(
+          (answer) => {
+            rl.off("close", fail);
+            resolve(answer);
+          },
+          (error: unknown) => {
+            rl.off("close", fail);
+            reject(error instanceof Error ? error : new Error(String(error)));
+          },
+        );
+      });
+    },
     close: () => rl.close(),
   };
 }
@@ -67,30 +121,107 @@ export async function askProjectName(
 }
 
 /**
- * 从选项表里选一项：输入序号（从 1 起）或直接输入 id，空输入取首项。
+ * 问描述：只问一次，回车即空。
  *
- * 两种取值都认，是因为脚本里写 `--framework vue` 更自然，而交互时按数字更省事；
- * 让同一套问答支持两种输入，参数模式与交互模式就不必分两套校验。
+ * 不重问也不校验：描述只影响清单里的一行说明，不影响任何路径与命令。为难一个
+ * 可以留空的输入框，只会让人多点几次回车。超长按上限截断——`package.json` 的
+ * 描述在工具链里本就是短文本，与其被别处悄悄截，不如自己截。
  */
-export async function askOption(
+export async function askDescription(
   io: PromptIo,
-  label: string,
-  options: readonly TemplateOption[],
-  fallbackId: string | undefined,
-  invalidText: string,
+  texts: PromptTexts,
 ): Promise<string> {
-  if (fallbackId !== undefined) return fallbackId;
+  const answer = await io.question(
+    `${texts.promptDescription}（${texts.descriptionHint}）：`,
+  );
+  return normalizeDescription(answer);
+}
+
+/**
+ * 问形态：一次多选，空格或逗号分隔，回车即空集。
+ *
+ * 选项表由调用方按「这一层有没有目录」筛过，所以这里看不到 `none`/`browser`/`ts`
+ * 这类缺省层——它们不是一个可以叠加的东西，而是「什么都不叠」。
+ *
+ * 互斥对由元数据的 `excludes` 推导，本文件不认识任何具体层 id：新增一层只要在
+ * 元数据里声明互斥，问答自动跟着变。撞上互斥就说穿是哪两层、然后重问同一问，
+ * 不静默丢掉其中一层——丢掉会让「我明明选了小程序」无法解释。
+ */
+export async function askLayers(
+  io: PromptIo,
+  texts: PromptTexts,
+  layers: readonly TemplateOption[],
+  catalogue: readonly TemplateOption[],
+): Promise<string[]> {
+  const labels = new Map(catalogue.map((option) => [option.id, option.label]));
+  const lines = layers
+    .map((option, index) => {
+      const excludes = (option.excludes ?? []).map(
+        (id) => labels.get(id) ?? id,
+      );
+      const tail =
+        excludes.length > 0 ? `  互斥：${excludes.join("、")}` : "  互斥：无";
+      return `  ${index + 1}. ${option.label} —— ${option.hint}${tail}`;
+    })
+    .join("\n");
+  process.stderr.write(`${texts.promptLayers}：\n${lines}\n`);
+  for (;;) {
+    const answer = (
+      await io.question(
+        `选择（1-${layers.length}，可多选，空格或逗号分隔；${texts.layersEmptyHint}）：`,
+      )
+    ).trim();
+    const picked = parseLayerAnswer(layers, answer);
+    if (picked === undefined) {
+      process.stderr.write(`${texts.layersInvalid}\n`);
+      continue;
+    }
+    const conflicts = findLayerConflicts(picked, catalogue);
+    if (conflicts.length === 0) return picked;
+    for (const [left, right] of conflicts) {
+      process.stderr.write(
+        `${texts.layersConflict}：${labels.get(left) ?? left} 与 ${labels.get(right) ?? right} 不能共存\n`,
+      );
+    }
+    process.stderr.write(`${texts.layersConflictHint}：`);
+  }
+}
+
+/**
+ * 目标目录已存在且有内容时问怎么处置。
+ *
+ * 三项的顺序是「保留 → 清空 → 取消」，但**回车取的是取消**：前面的选项会改动
+ * 磁盘上的既有文件，回车只是「没想好」，不该替使用者做破坏性决定。
+ */
+export async function askExisting(
+  io: PromptIo,
+  texts: PromptTexts,
+): Promise<ExistingTarget> {
+  const options: readonly TemplateOption[] = [
+    {
+      id: "ignore",
+      label: texts.existingIgnore,
+      hint: texts.existingIgnoreHint,
+    },
+    { id: "clear", label: texts.existingClear, hint: texts.existingClearHint },
+    {
+      id: "cancel",
+      label: texts.existingCancel,
+      hint: texts.existingCancelHint,
+    },
+  ];
   const lines = options
     .map((option, index) => `  ${index + 1}. ${option.label} —— ${option.hint}`)
     .join("\n");
-  process.stderr.write(`${label}：\n${lines}\n`);
+  process.stderr.write(`${texts.promptExisting}：\n${lines}\n`);
   for (;;) {
     const answer = (
-      await io.question(`选择（1-${options.length}，回车取 1）：`)
+      await io.question(`选择（1-${options.length}，回车取消）：`)
     ).trim();
+    if (answer === "") return "cancel";
     const picked = pickOption(options, answer);
-    if (picked !== undefined) return picked;
-    process.stderr.write(`${invalidText}\n`);
+    if (picked !== undefined) return picked as ExistingTarget;
+    process.stderr.write(`${texts.promptExisting}：${answer}\n`);
   }
 }
 
@@ -115,3 +246,71 @@ export function pickOption(
   }
   return undefined;
 }
+
+/**
+ * 把一次多选输入解析成层 id 列表，保序去重；有认不出的编号或名字时返回 undefined。
+ *
+ * 认两种写法（序号与 id）是为了脚本与手敲都顺手；认空格、半角逗号与全角逗号是因为
+ * 中文输入法下逗号常常是全角的，为这个报错只会让人困惑。
+ *
+ * 空输入是空集而**不是**错误：不选任何层就是「只用骨架」，那是最常见的形态。
+ */
+export function parseLayerAnswer(
+  layers: readonly TemplateOption[],
+  answer: string,
+): string[] | undefined {
+  const tokens = answer
+    .split(/[\s,，]+/)
+    .map((token) => token.trim())
+    .filter((token) => token !== "");
+  if (tokens.length === 0) return [];
+  const out: string[] = [];
+  for (const token of tokens) {
+    const picked = pickOptionStrict(layers, token);
+    if (picked === undefined) return undefined;
+    if (!out.includes(picked)) out.push(picked);
+  }
+  return out;
+}
+
+/**
+ * 从选中的层里找出互斥对。
+ *
+ * 只看「选中的这两层彼此排斥」，不看谁先声明的：`excludes` 单边声明即生效，
+ * 因此两边都写了也只算一对。
+ */
+export function findLayerConflicts(
+  selected: readonly string[],
+  catalogue: readonly TemplateOption[],
+): LayerConflict[] {
+  const chosen = new Set(selected);
+  const seen = new Set<string>();
+  const out: LayerConflict[] = [];
+  for (const option of catalogue) {
+    if (!chosen.has(option.id)) continue;
+    for (const excluded of option.excludes ?? []) {
+      if (!chosen.has(excluded)) continue;
+      const key = [option.id, excluded].sort().join("\u0000");
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push([option.id, excluded]);
+    }
+  }
+  return out;
+}
+
+/** 与 `pickOption` 同义，但不把空输入当首项：多选里空输入是「什么都不选」 */
+function pickOptionStrict(
+  options: readonly TemplateOption[],
+  token: string,
+): string | undefined {
+  if (token === "") return undefined;
+  const index = Number(token);
+  if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+    return options[index - 1].id;
+  }
+  for (const option of options) {
+    if (option.id === token) return option.id;
+  }
+  return undefined;
+}

package/src/cli/stage.ts

@@ -0,0 +1,113 @@
+/**
+ * 生成阶段：查版本 → 写文件 → 可选安装 → 打印后续步骤。
+ *
+ * 为什么与参数解析分开：这一段对使用者是「正在干活」的进度叙事，对测试是纯副作用，
+ * 而参数解析是纯函数。两者放在一个文件里，任何一边的改动都要重新读另一边的代码。
+ *
+ * 入参自带形状而不复用命令行类型：本文件不需要知道参数是怎么解析出来的，只认得
+ * 「要生成什么」。这也让方向保持单向——参数层依赖这里，这里不回头依赖参数层。
+ */
+import { resolve as resolvePath } from "node:path";
+import { currentPackageManager, defaultCreateTexts } from "../shared/index.ts";
+import {
+  collectDependencyNames,
+  generateProject,
+  layerBases,
+  type ExistingTarget,
+} from "../generate/index.ts";
+import {
+  checkEngineCompatibility,
+  resolveVersions,
+  type TemplateMeta,
+} from "../registry/index.ts";
+import { installProject, renderNextSteps } from "./install.ts";
+
+/** 生成阶段需要的信息；`description` 为空串表示产物里不出现该字段 */
+export interface StageOptions {
+  readonly meta: TemplateMeta;
+  readonly templateRoot: string;
+  /** 生成到哪个目录下；缺省为当前目录 */
+  readonly dir: string | undefined;
+  readonly projectName: string;
+  readonly description: string;
+  readonly framework: string;
+  readonly shell: string;
+  readonly sources: string;
+  readonly existing: ExistingTarget;
+  readonly install: boolean;
+}
+
+/**
+ * 执行一次生成，返回进程退出码。
+ *
+ * 版本查询与兼容性判定都排在写盘之前：模板要求的引擎还没发布时，生成出来的工程
+ * 装不上，让它失败在「什么都没写」的时刻，而不是在别人的工程里第一次启动时。
+ */
+export async function runStage(options: StageOptions): Promise<number> {
+  const texts = defaultCreateTexts;
+  const manager = currentPackageManager();
+  const targetBase = resolvePath(options.dir ?? process.cwd());
+  const layout = {
+    templateRoot: options.templateRoot,
+    targetBase,
+    projectName: options.projectName,
+    description: options.description,
+    framework: options.framework,
+    shell: options.shell,
+    sources: options.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`);
+  }
+  const incompatible = checkEngineCompatibility(
+    options.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: options.existing,
+      resolved,
+    });
+  } catch (error) {
+    process.stderr.write(`${describe(error)}\n`);
+    return 1;
+  }
+
+  let installed = false;
+  if (options.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;
+}
+
+/** 把异常折成一行提示：只暴露信息，不暴露堆栈 */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/generate/index.ts

@@ -7,11 +7,16 @@ export {
   collectDependencyNames,
   DEFAULT_SOURCES,
   generateProject,
+  isOccupied,
   layerBases,
-  pinnedNames,
+  projectDirOf,
   SKELETON_DIR,
 } from "./project.ts";
-export type { GenerateOptions, GenerateResult } from "./project.ts";
+export type {
+  ExistingTarget,
+  GenerateOptions,
+  GenerateResult,
+} from "./project.ts";
 export {
   isTextPath,
   PLACEHOLDERS,