@lingfan-engine/create 0.3.3 → 0.3.4

package/bin/create.mjs

@@ -8,11 +8,11 @@
  * `src/cli/cli.ts`，也不该被迫装一整套构建链。垫片用本包自带依赖 `tsx` 装载真实 CLI，
  * 呈现与编排逻辑仍然只有一份。
  *
- * 用法：`npm create @lingfan-engine [工程名] [-- --framework vue --shell browser]`；
+ * 用法：`npm create @lingfan-engine [工程名] [-- --template vue-tauri]`；
  * 不带参数即进入交互问答。
  */
 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.4",
   "type": "module",
   "description": "工程生成器：从模板骨架生成新工程，可选框架与壳",
   "license": "Apache-2.0",

package/src/cli/cli.ts

@@ -5,14 +5,16 @@
  * `generate` 域，「版本从哪来」在 `registry` 域。本文件只负责把这些串起来，
  * 并把失败转成人能读的提示与退出码——库代码一律抛异常，只有这里决定措辞。
  */
-import { spawn } from "node:child_process";
 import { resolve as resolvePath } from "node:path";
-import { defaultCreateTexts } from "../shared/index.ts";
+import { currentPackageManager, 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,
@@ -22,20 +24,24 @@ import {
   type TemplateMeta,
 } from "../registry/index.ts";
 import {
+  askExisting,
   askOption,
   askProjectName,
   createTerminalIo,
   type PromptTexts,
 } from "./prompts.ts";
+import { installProject, renderNextSteps } from "./install.ts";
 
 /** 解析后的命令行参数；缺席项为 undefined，交由问答或模板缺省值补 */
 export interface CreateArgs {
   readonly projectName?: 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 +54,19 @@ class ArgError extends Error {}
  *
  * 支持 `--flag value` 与 `--flag=value` 两种写法：前者是手敲的习惯，
  * 后者在脚本里拼接更省事，两者都认不需要额外成本。
+ *
+ * 依赖缺省**不**安装：装依赖是几十秒到几分钟的副作用，脚本里更希望它显式请求
+ * （`--install`）。旧脚本里的 `--no-install` 仍然认，等于什么都不做。
  */
 export function parseArgs(argv: readonly string[]): CreateArgs {
   let projectName: 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 +83,9 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
       return next;
     };
     switch (flag) {
+      case "--template":
+        template = takeValue();
+        break;
       case "-f":
       case "--framework":
         framework = takeValue();
@@ -88,9 +102,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 +127,18 @@ export function parseArgs(argv: readonly string[]): CreateArgs {
         projectName = flag;
     }
   }
-  return { projectName, framework, shell, sources, dir, install, yes, help };
+  return {
+    projectName,
+    template,
+    framework,
+    shell,
+    sources,
+    dir,
+    install,
+    existing,
+    yes,
+    help,
+  };
 }
 
 /** 拆出 `--flag=value`；无等号时第二项为 undefined */
@@ -153,9 +184,11 @@ export async function runCreateCli(argv: readonly string[]): Promise<number> {
   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,
+      args.framework ?? preset.framework,
       meta,
       promptTexts,
       io,
@@ -163,20 +196,26 @@ export async function runCreateCli(argv: readonly string[]): Promise<number> {
     if (framework === undefined) return 1;
     const shell = await resolveOption(
       "shell",
-      args.shell,
+      args.shell ?? preset.shell,
       meta,
       promptTexts,
       io,
     );
     if (shell === undefined) return 1;
-    const sources = await resolveOption(
-      "sources",
-      args.sources,
-      meta,
-      promptTexts,
+    // 故事源不再提问：骨架自带整条 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;
+    }
+    const existing = await resolveExisting({
+      args,
+      projectName,
       io,
-    );
-    if (sources === undefined) return 1;
+      texts: promptTexts,
+    });
+    if (existing === undefined) return 1;
     return await generate({
       args,
       meta,
@@ -185,12 +224,81 @@ export async function runCreateCli(argv: readonly string[]): Promise<number> {
       framework,
       shell,
       sources,
+      existing,
     });
   } 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 };
+}
+
+/**
+ * 决定目标目录非空时怎么处置。
+ *
+ * 缺省是取消：覆盖别人的工程无法撤销，`--yes` 也不该替人做这个决定。
+ * `--overwrite` 是显式表态，交互模式下也会问一次。
+ */
+async function resolveExisting(input: {
+  readonly args: CreateArgs;
+  readonly projectName: string;
+  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,
+  });
+  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;
+  }
+  const picked = await askExisting(input.io, input.texts);
+  if (picked === "cancel") {
+    process.stderr.write(`${input.texts.targetExists}：${projectDir}\n`);
+    return undefined;
+  }
+  return picked;
+}
+
 /** 生成一步：查版本 → 写文件 → 可选安装 → 打印后续步骤 */
 async function generate(input: {
   readonly args: CreateArgs;
@@ -200,8 +308,10 @@ async function generate(input: {
   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,
@@ -233,7 +343,7 @@ async function generate(input: {
   process.stderr.write(`${texts.stageCopy}\n`);
   let result;
   try {
-    result = generateProject({ ...layout, resolved });
+    result = generateProject({ ...layout, existing: input.existing, resolved });
   } catch (error) {
     process.stderr.write(`${describe(error)}\n`);
     return 1;
@@ -242,7 +352,7 @@ async function generate(input: {
   let installed = false;
   if (input.args.install) {
     process.stderr.write(`${texts.stageInstall}\n`);
-    installed = await install(result.projectDir);
+    installed = await installProject(result.projectDir, manager);
     if (!installed) process.stderr.write(`${texts.warnInstallFailed}\n`);
   }
 
@@ -253,7 +363,7 @@ async function generate(input: {
       `共 ${result.fileCount} 个文件，框架 ${result.framework}，壳 ${result.shell}，故事源 ${result.sources}`,
       "",
       installed ? "依赖已安装。" : "依赖未安装。",
-      texts.nextSteps.split("<name>").join(result.projectDir),
+      renderNextSteps(result.projectDir, manager, texts),
       "",
     ].join("\n"),
   );
@@ -278,36 +388,24 @@ async function resolveName(
 }
 
 /**
- * 解析框架/壳/故事源：必须真实存在对应的叠加层，否则报错。
+ * 解析框架/壳：值必须在模板声明的表里。
  *
- * 只校验「模板声明过」而不校验「目录存在」会放过一种情况：元数据写了 `vue`
- * 但仓库里没有 `overlays/vue`，生成出来的工程静默缺少该框架的文件。
+ * 表是唯一事实来源——元数据没声明的形态，叠加层目录未必存在，放过去会生成出
+ * 静默缺文件的工程。故事源不在这里判：它只剩「作者手写 `.story`」这一种偏离，
+ * 由调用方按同一张表查一次即可。
  */
 async function resolveOption(
-  kind: "framework" | "shell" | "sources",
+  kind: "framework" | "shell",
   value: string | undefined,
   meta: TemplateMeta,
-  texts: PromptTexts & { readonly overlayMissing: string },
+  texts: PromptTexts,
   io: Parameters<typeof askOption>[0] | undefined,
 ): Promise<string | undefined> {
-  const options =
-    kind === "framework"
-      ? meta.frameworks
-      : kind === "shell"
-        ? meta.shells
-        : meta.sources;
+  const options = kind === "framework" ? meta.frameworks : meta.shells;
   const invalidText =
-    kind === "framework"
-      ? texts.frameworkUnknown
-      : kind === "shell"
-        ? texts.shellUnknown
-        : texts.sourcesUnknown;
+    kind === "framework" ? texts.frameworkUnknown : texts.shellUnknown;
   const label =
-    kind === "framework"
-      ? texts.promptFramework
-      : kind === "shell"
-        ? texts.promptShell
-        : texts.promptSources;
+    kind === "framework" ? texts.promptFramework : texts.promptShell;
   const picked =
     value !== undefined || io === undefined
       ? (value ?? options[0]?.id)
@@ -319,24 +417,6 @@ async function resolveOption(
   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);

package/src/cli/index.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI 域唯一出口。
+ *
+ * 只做转发：参数解析（`cli.ts`）、交互问答（`prompts.ts`）、依赖安装与后续命令
+ * 渲染（`install.ts`）三层各自成文件，调用方从这里进出，不穿过文件名。
+ */
+export { parseArgs, runCreateCli } from "./cli.ts";
+export type { CreateArgs } from "./cli.ts";
+export {
+  askExisting,
+  askOption,
+  askProjectName,
+  createTerminalIo,
+  pickOption,
+} from "./prompts.ts";
+export type { PromptIo, PromptTexts } from "./prompts.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,8 +1,11 @@
 /**
  * 交互问答。
  *
- * 生成器要问四件事：工程名、框架、壳、故事源形态。四项都能用命令行参数预先给定——CI、
- * 脚本、或「我已经知道要什么」的人不该被问答拦住，因此问答只在参数缺席时发生。
+ * 生成器要问三件事：工程名、框架、壳。故事源形态不再是问题——骨架自带整条 TS
+ * 创作链，它就是缺省形态；要手艺写的 `.story` 用 `--sources story` 指定即可。
+ *
+ * 目标目录非空时另问一次怎么处置：那是覆盖别人的东西，必须由使用者当场表态，
+ * 不能拿缺省值糊过去（缺省是取消）。
  *
  * 实现只用 `node:readline` 的 promise 版：它随 Node 自带，不引第三方交互库。
  * 提问写 stderr 而不是 stdout，产物路径之类的结果才走 stdout，这样
@@ -11,18 +14,24 @@
 import { createInterface } from "node:readline/promises";
 import { isValidProjectName, suggestProjectName } from "../shared/index.ts";
 import type { 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 promptExisting: string;
   readonly nameRequired: string;
   readonly nameInvalid: string;
   readonly frameworkUnknown: string;
   readonly shellUnknown: string;
-  readonly sourcesUnknown: string;
+  readonly existingIgnore: string;
+  readonly existingIgnoreHint: string;
+  readonly existingClear: string;
+  readonly existingClearHint: string;
+  readonly existingCancel: string;
+  readonly existingCancelHint: string;
 }
 
 /** 问答依赖的输入输出面；默认接真实终端，测试可换成脚本化实现 */
@@ -94,6 +103,44 @@ export async function askOption(
   }
 }
 
+/**
+ * 目标目录已存在且有内容时问怎么处置。
+ *
+ * 三项的顺序是「保留 → 清空 → 取消」，但**回车取的是取消**：前面的选项会改动
+ * 磁盘上的既有文件，回车只是「没想好」，不该替使用者做破坏性决定。
+ */
+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(`${texts.promptExisting}：\n${lines}\n`);
+  for (;;) {
+    const answer = (
+      await io.question(`选择（1-${options.length}，回车取消）：`)
+    ).trim();
+    if (answer === "") return "cancel";
+    const picked = pickOption(options, answer);
+    if (picked !== undefined) return picked as ExistingTarget;
+    process.stderr.write(`${texts.promptExisting}：${answer}\n`);
+  }
+}
+
 /**
  * 把一次输入解析成选项 id；解析不出返回 undefined。
  *

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,