@lingfan-engine/create 0.0.0-stage → 0.1.5

package/src/generate/dotfiles.ts

@@ -0,0 +1,27 @@
+/**
+ * 点文件名还原。
+ *
+ * npm 把包安装到 `node_modules` 时，会把包内的 `.gitignore` 改名成 `.npmignore`
+ * （免得某个依赖的忽略规则反过来影响使用者的仓库），但 tarball 里仍然是原名——
+ * 同一个文件在「打包后」与「安装后」两个时刻叫法不同。
+ *
+ * 生成器读的是安装后的目录，所以模板里把这类文件存成不带点开头的普通名字，
+ * 由本表在产物里改回去。不还原的后果是具体的：新工程拿不到 `.gitignore`
+ * （`node_modules/`、`dist/`、`Resources/Saves/` 会被误提交进版本库），
+ * 却多出一个在工程里没有任何作用的 `.npmignore`。
+ *
+ * 只处理工程根的那一层：嵌套目录里的同名文件由使用者自己管，模板不带。
+ */
+
+/** 安装期被 npm 改名过的文件名 → 产物里应有的名字 */
+const RESTORED = new Map([["gitignore", ".gitignore"]]);
+
+/**
+ * 把模板里为了躲开改名而写的普通文件名还原成点文件名。
+ *
+ * 只认工程根：`path` 里出现分隔符时原样返回，避免动到使用者目录里的同名文件。
+ */
+export function restoreDotfile(path: string): string {
+  if (path.includes("/")) return path;
+  return RESTORED.get(path) ?? path;
+}

package/src/generate/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 生成域的公共出口。
+ *
+ * 只做转发：域外的调用方（CLI、测试）只认这一处，内部文件改位置不会外溢。
+ */
+export {
+  collectDependencyNames,
+  generateProject,
+  layerBases,
+  pinnedNames,
+  SKELETON_DIR,
+} from "./project.ts";
+export type { GenerateOptions, GenerateResult } from "./project.ts";
+export {
+  isTextPath,
+  PLACEHOLDERS,
+  replaceInFile,
+  replacePlaceholders,
+} from "./replace.ts";
+export { restoreDotfile } from "./dotfiles.ts";

package/src/generate/project.ts

@@ -0,0 +1,279 @@
+/**
+ * 生成编排：读模板 → 合叠加层 → 落版本 → 替换占位符 → 写盘。
+ *
+ * 顺序是有依赖的，不能互换：
+ * 1. 合并拿到完整文件表（叠加层已覆盖骨架的同名文件）；
+ * 2. 把 `package.patch.json` 的增量深合进 `package.json`，并在此之上写版本号——
+ *    叠加层新增的依赖也要被解析到最新版，所以版本注入必须发生在合并之后；
+ * 3. 最后做占位符替换，产物文本因此与磁盘上写出的字节完全一致。
+ *
+ * 写盘是「全有或全无」的：先算出全部产物再逐个写，中途不会因为某个文件失败而留下半个工程。
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  listFiles,
+  mergeLayers,
+  PATCH_SUFFIX,
+  type PendingFile,
+} from "../overlay/index.ts";
+import {
+  applyResolvedVersions,
+  overlayDirOf,
+  readTemplateMeta,
+} from "../registry/index.ts";
+import { replaceInFile } from "./replace.ts";
+import { restoreDotfile } from "./dotfiles.ts";
+
+/** 骨架目录名：占位符本身，也是模板里唯一随框架无关的目录 */
+export const SKELETON_DIR = "__PROJECT__";
+
+/** 生成参数 */
+export interface GenerateOptions {
+  /** 模板根目录（含 `template-meta.json` 与骨架目录） */
+  readonly templateRoot: string;
+  /** 生成到哪个目录下 */
+  readonly targetBase: string;
+  /** 工程名：目录名、包名、清单 id 与页面标题都用它 */
+  readonly projectName: string;
+  /** 框架叠加层 id */
+  readonly framework: string;
+  /** 壳叠加层 id */
+  readonly shell: string;
+  /** 引擎包的最新版本；缺席项沿用模板记录的值 */
+  readonly resolved: ReadonlyMap<string, string>;
+}
+
+/** 生成结果 */
+export interface GenerateResult {
+  /** 生成出来的工程根目录绝对路径 */
+  readonly projectDir: string;
+  /** 写出的文件数 */
+  readonly fileCount: number;
+  /** 实际采用的框架与壳 */
+  readonly framework: string;
+  readonly shell: string;
+}
+
+/**
+ * 生成一个工程。
+ *
+ * 只会新建目录：目标已存在且非空时抛错，不做覆盖也不做增量合并——覆盖别人的工程
+ * 无法撤销，宁可让使用者先自己删。
+ */
+export function generateProject(options: GenerateOptions): GenerateResult {
+  const meta = readTemplateMeta(options.templateRoot);
+  const projectDir = join(options.targetBase, options.projectName);
+  if (isOccupied(projectDir)) {
+    throw new Error(`目标目录已存在且非空：${projectDir}`);
+  }
+  const merged = mergeLayers(layerBases(options));
+  const files = finalize(
+    merged.files,
+    merged.patch,
+    options.resolved,
+    meta.placeholder,
+    options.projectName,
+  );
+  mkdirSync(projectDir, { recursive: true });
+  for (const file of files) {
+    const target = join(projectDir, file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+  }
+  return {
+    projectDir,
+    fileCount: files.length,
+    framework: options.framework,
+    shell: options.shell,
+  };
+}
+
+/**
+ * 依次列出要合并的目录：骨架在前，框架层次之，壳层最后。
+ *
+ * 缺席的叠加层直接跳过——缺省项（`none` / `browser`）本就没有目录，
+ * 这不是错误，只是「这一层什么都不加」。
+ */
+export function layerBases(options: GenerateOptions): string[] {
+  const bases = [join(options.templateRoot, SKELETON_DIR)];
+  for (const id of unique([options.framework, options.shell])) {
+    const dir = overlayDirOf(options.templateRoot, id);
+    if (dir !== undefined && !bases.includes(dir)) bases.push(dir);
+  }
+  return bases;
+}
+
+/** 目标目录是否已被占用：存在且含有内容即算占用，空目录可以复用 */
+function isOccupied(dir: string): boolean {
+  if (!existsSync(dir)) return false;
+  return readdirSync(dir).length > 0;
+}
+
+/**
+ * 收集这些层里出现过的依赖名。
+ *
+ * 只读 `package.json` 与根目录的 `*.patch.json`：前者是骨架写的依赖，后者是叠加层
+ * 追加的依赖，两处之外不会有依赖声明。顺序去重，供版本查询一次问完。
+ */
+export function collectDependencyNames(bases: readonly string[]): string[] {
+  const names = new Set<string>();
+  for (const base of bases) {
+    if (!existsSync(base)) continue;
+    for (const path of listFiles(base)) {
+      const isManifest = path === "package.json";
+      const isPatch = !path.includes("/") && path.endsWith(PATCH_SUFFIX);
+      if (!isManifest && !isPatch) continue;
+      const parsed = JSON.parse(
+        readFileSync(join(base, path), "utf8"),
+      ) as Record<string, unknown>;
+      for (const field of ["dependencies", "devDependencies"] as const) {
+        const table = parsed[field];
+        if (isStringMap(table)) {
+          for (const name of Object.keys(table)) names.add(name);
+        }
+      }
+    }
+  }
+  return [...names];
+}
+
+/**
+ * 收尾：工程清单合并版本、点文件名还原、全部文件替换占位符。
+ *
+ * 单独拆出来是为了可测——测试要能在不写盘的前提下断言产物字节，
+ * 写盘那一步与「算出该写什么」分开后，判据就不必碰真实文件系统。
+ *
+ * 点文件还原必须在这里发生：模板里存的是躲开 npm 改名的普通名（见 `dotfiles.ts`），
+ * 产物路径要写回带点的形态，占位符替换才按产物路径判文本/二进制。
+ */
+export function finalize(
+  files: readonly PendingFile[],
+  patch: Readonly<Record<string, unknown>> | undefined,
+  resolved: ReadonlyMap<string, string>,
+  placeholder: string,
+  projectName: string,
+): PendingFile[] {
+  return files.map((file) => {
+    const path = restoreDotfile(file.path);
+    const content =
+      file.path === "package.json"
+        ? renderManifest(file.content, patch, resolved)
+        : file.content;
+    return {
+      path,
+      content: replaceInFile(path, content, placeholder, projectName),
+    };
+  });
+}
+
+/**
+ * 把增量与版本号写进 `package.json`。
+ *
+ * 依赖表只改「已经存在的键」：模板决定依赖集合，生成器不是包管理器，
+ * 不会凭 registry 上的存在性往工程里塞新包。叠加层 `create.pinned` 点名的包
+ * 不参与版本解析，保留模板记录的区间——上游版本兼容性只有模板作者知道。
+ */
+function renderManifest(
+  content: Buffer,
+  patch: Readonly<Record<string, unknown>> | undefined,
+  resolved: ReadonlyMap<string, string>,
+): Buffer {
+  const manifest = JSON.parse(content.toString("utf8")) as Record<
+    string,
+    unknown
+  >;
+  const withPatch =
+    patch === undefined ? manifest : mergeManifest(manifest, patch);
+  delete withPatch[CREATE_FIELD];
+  const pinned = new Set(pinnedNames(patch));
+  for (const field of ["dependencies", "devDependencies"] as const) {
+    const table = withPatch[field];
+    if (isStringMap(table)) {
+      withPatch[field] = applyResolvedVersions(
+        table,
+        withoutNames(resolved, pinned),
+      );
+    }
+  }
+  return Buffer.from(`${JSON.stringify(withPatch, null, 2)}\n`, "utf8");
+}
+
+/** 去掉被钉住的包：它们不进解析结果表，版本区间因此保持模板原值 */
+function withoutNames(
+  resolved: ReadonlyMap<string, string>,
+  names: ReadonlySet<string>,
+): Map<string, string> {
+  if (names.size === 0) return new Map(resolved);
+  const out = new Map<string, string>();
+  for (const [name, version] of resolved) {
+    if (!names.has(name)) out.set(name, version);
+  }
+  return out;
+}
+
+/** 顶层深合并：嵌套对象递归，其余（含数组）由增量整体取代 */
+function mergeManifest(
+  base: Record<string, unknown>,
+  patch: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    const current = out[key];
+    out[key] =
+      isStringMap(current) && isStringMap(value)
+        ? { ...current, ...value }
+        : value;
+  }
+  return out;
+}
+
+/**
+ * 生成器专用字段名。
+ *
+ * 叠加层可以用它声明「生成期要做的事」，这些内容不属于产物清单，写盘前必须抹掉——
+ * 否则新工程的 `package.json` 里会多出一个 npm 不认识、读者也不懂的字段。
+ */
+const CREATE_FIELD = "create";
+
+/**
+ * 读叠加层声明的「不要跟最新版」的依赖名。
+ *
+ * 存在的理由：模板希望依赖尽量新，但上游并非都兼容——`vue-tsc` 在 `typescript` 7 上
+ * 会因 `./lib/tsc` 不再导出而直接崩，这类约束只有模板作者知道。钉住的包保留模板
+ * 记录的版本区间，其余照常解析到最新。
+ */
+export function pinnedNames(
+  patch: Readonly<Record<string, unknown>> | undefined,
+): string[] {
+  if (patch === undefined) return [];
+  const section = patch[CREATE_FIELD];
+  if (!isPlainRecord(section)) return [];
+  const pinned = section.pinned;
+  if (!Array.isArray(pinned)) return [];
+  return pinned.filter((item): item is string => typeof item === "string");
+}
+
+/** 只认普通对象：数组与 null 不算 */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 只认「字符串到字符串」的表：依赖就是这个形状 */
+function isStringMap(value: unknown): value is Record<string, string> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every((item) => typeof item === "string");
+}
+
+/** 去重但保序：框架与壳偶有同名层（如都用 browser），只要合并一次 */
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}

package/src/generate/replace.ts

@@ -0,0 +1,91 @@
+/**
+ * 占位符替换。
+ *
+ * 模板里的占位符有两套大小写形态：`__PROJECT__`（清单 id/name、页面标题、目录名）与
+ * `__project__`（`package.json` 的 name，npm 要求小写）。工程名本身只允许小写，
+ * 因此两者最终得到同一个字符串；分开列出来是为了让「哪里用了哪种形态」一眼可查，
+ * 而不是靠一次全量替换把不该动的字节也改了。
+ *
+ * 替换面只覆盖**文本文件**：模板里有字体、图片这类二进制资源，逐字节做字符串替换
+ * 会把它们改坏（一旦命中就整块错位），所以先判类型再决定是否处理。
+ */
+
+/** 模板二进制资源的扩展名；命中即按字节原样复制，不做文本替换 */
+const BINARY_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".avif",
+  ".tiff",
+  ".ico",
+  ".icns",
+  ".ttf",
+  ".otf",
+  ".ttc",
+  ".woff",
+  ".woff2",
+  ".mp3",
+  ".ogg",
+  ".wav",
+  ".m4a",
+  ".flac",
+  ".mp4",
+  ".webm",
+  ".pdf",
+  ".zip",
+  ".gz",
+  ".7z",
+  ".rar",
+  ".wasm",
+]);
+
+/** 已知的模板占位符形态 → 说明（生成时全部替换为工程名） */
+export const PLACEHOLDERS = ["__PROJECT__", "__project__"] as const;
+
+/** 按扩展名判是否文本；未知扩展名一律当文本（模板里的无扩展名文件都是文本） */
+export function isTextPath(path: string): boolean {
+  const dot = path.lastIndexOf(".");
+  if (dot < 0) return true;
+  return !BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+
+/**
+ * 在文本里替换全部占位符。
+ *
+ * `placeholder` 是模板声明的权威占位符（当前为 `__PROJECT__`）；同时替换它的小写形态，
+ * 因为 `package.json` 的 name 必须小写，模板里就写成 `__project__`——只替换大写形态
+ * 会让新工程的包名仍然是占位符。
+ */
+export function replacePlaceholders(
+  text: string,
+  placeholder: string,
+  projectName: string,
+): string {
+  const forms = new Set([placeholder, placeholder.toLowerCase()]);
+  let out = text;
+  for (const form of forms) {
+    out = out.split(form).join(projectName);
+  }
+  return out;
+}
+
+/**
+ * 对一份文件内容做占位符替换：文本走替换，二进制原样返回。
+ *
+ * 返回 `Buffer` 是为了让调用方写盘时不必关心来源是文本还是字节。
+ */
+export function replaceInFile(
+  path: string,
+  content: Buffer,
+  placeholder: string,
+  projectName: string,
+): Buffer {
+  if (!isTextPath(path)) return content;
+  return Buffer.from(
+    replacePlaceholders(content.toString("utf8"), placeholder, projectName),
+    "utf8",
+  );
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * 包唯一公共入口。
+ *
+ * 只做转发：库里没有「怎么问」与「怎么打印」的实现，那些属于 CLI；
+ * 这里暴露的是「给定参数就能算出产物」的那一层，供测试与将来的图形化前端复用。
+ */
+export {
+  collectDependencyNames,
+  generateProject,
+  layerBases,
+  SKELETON_DIR,
+  isTextPath,
+  PLACEHOLDERS,
+  replaceInFile,
+  replacePlaceholders,
+} from "./generate/index.ts";
+export type { GenerateOptions, GenerateResult } from "./generate/index.ts";
+export {
+  deepMerge,
+  listFiles,
+  mergeLayers,
+  readLayer,
+  PATCH_SUFFIX,
+} from "./overlay/index.ts";
+export type { MergedLayer, PendingFile } from "./overlay/index.ts";
+export {
+  applyResolvedVersions,
+  fetchLatestVersion,
+  overlayDirOf,
+  readTemplateMeta,
+  resolveTemplateRoot,
+  resolveVersions,
+  OVERLAY_DIR,
+} from "./registry/index.ts";
+export type {
+  ResolvedVersion,
+  TemplateMeta,
+  TemplateOption,
+} from "./registry/index.ts";
+export {
+  caretRange,
+  isValidProjectName,
+  suggestProjectName,
+} from "./shared/index.ts";
+export { defaultCreateTexts } from "./shared/index.ts";
+export type { CreateTexts } from "./shared/index.ts";

package/src/overlay/index.ts

@@ -0,0 +1,10 @@
+/** overlay 域唯一出口：叠加层读取与三层合并规则。 */
+export {
+  deepMerge,
+  listFiles,
+  mergeLayers,
+  readLayer,
+  PATCH_SUFFIX,
+  type MergedLayer,
+  type PendingFile,
+} from "./merge.ts";

package/src/overlay/merge.ts

@@ -0,0 +1,143 @@
+/**
+ * 叠加层合并规则。
+ *
+ * 模板分两层：骨架（`__PROJECT__`，框架无关，任何框架都要）与叠加层
+ * （`overlays/<id>`，只含该框架/壳特有的文件）。合并只有三条规则，全部在这里：
+ *
+ * 1. **同路径覆盖**——叠加层里与骨架同名的文件整体替换骨架那份。
+ * 2. **`*.patch.json` 深合并**——叠加层里名为 `package.patch.json` 的文件不是产物，
+ *    而是增量：解析成对象后深合进同目录的 `package.json`（这个目录下就是工程根）。
+ *    用增量而不是整份替换，是为了让骨架的脚本与依赖始终是唯一事实来源，
+ *    叠加层只说「我要多一个依赖、多一条脚本」。
+ * 3. 其余文件按相对路径复制。
+ *
+ * 占位符替换不在这里做——它是纯文本层面的最后一刀，见 `generate` 域。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** 叠加层的增量文件名；该名本身不进产物 */
+export const PATCH_SUFFIX = ".patch.json";
+
+/**
+ * 一份待写文件：工程内相对路径（posix 分隔）+ 内容。
+ *
+ * 内容一律是字节：模板里有字体、图片这类资源，按文本读会在遇到非法 UTF-8 时
+ * 被静默替换成替换符，写回去就把资源改坏了。文本文件在需要时再解码。
+ */
+export interface PendingFile {
+  readonly path: string;
+  readonly content: Buffer;
+}
+
+/**
+ * 递归列出一个目录下的全部文件（相对 `base` 的 posix 路径）。
+ *
+ * 跳过 `node_modules`、`dist`、`.git` 与 Saves：它们是运行/构建副产物，
+ * 不该被复制进新工程。判定按目录名精确匹配，不做后缀猜测。
+ */
+export function listFiles(base: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir)) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        out.push(relative(base, full).split(sep).join("/"));
+      }
+    }
+  };
+  walk(base);
+  return out.sort();
+}
+
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", "Saves"]);
+
+/**
+ * 把一层目录读成待写文件表；`*.patch.json` 被解析成增量单独返回。
+ *
+ * 增量不混进文件表——它没有对应的产物文件，合并对象语义与「写一份文本」不同，
+ * 混在一起会让调用方每次都要多判一次。
+ */
+export function readLayer(base: string): {
+  readonly files: PendingFile[];
+  readonly patch: Readonly<Record<string, unknown>> | undefined;
+} {
+  const files: PendingFile[] = [];
+  let patch: Record<string, unknown> | undefined;
+  for (const path of listFiles(base)) {
+    const name = path.split("/").pop() ?? path;
+    if (name.endsWith(PATCH_SUFFIX)) {
+      // 只认工程根的那份：嵌套目录里的同名文件按普通文件处理，
+      // 免得某个框架在子目录放一个只对子目录包生效的清单时被误当工程清单。
+      if (!path.includes("/")) {
+        patch = JSON.parse(readFileSync(join(base, path), "utf8")) as Record<
+          string,
+          unknown
+        >;
+        continue;
+      }
+    }
+    files.push({ path, content: readFileSync(join(base, path)) });
+  }
+  return { files, patch };
+}
+
+/** 合并结果：文件表（后写覆盖先写）+ 合并后的工程清单增量 */
+export interface MergedLayer {
+  readonly files: readonly PendingFile[];
+  readonly patch: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * 依次合并多层目录，先出现的层在前（骨架先，叠加层后）。
+ *
+ * 同路径后者覆盖前者；增量逐层深合并。返回的文件表保持「每个路径只出现一次」，
+ * 值是最后写入的那份——调用方可以直接顺序写盘，不需要自己判重。
+ */
+export function mergeLayers(bases: readonly string[]): MergedLayer {
+  const byPath = new Map<string, PendingFile>();
+  let patch: Record<string, unknown> = {};
+  let hasPatch = false;
+  for (const base of bases) {
+    if (!existsSync(base)) continue;
+    const layer = readLayer(base);
+    for (const file of layer.files) byPath.set(file.path, file);
+    if (layer.patch) {
+      patch = deepMerge(patch, layer.patch);
+      hasPatch = true;
+    }
+  }
+  return {
+    files: [...byPath.values()],
+    patch: hasPatch ? patch : undefined,
+  };
+}
+
+/**
+ * 深合并：普通对象逐键递归，数组与标量由后者整体取代。
+ *
+ * 数组不拼接是刻意的——`files`、`keywords` 这类字段拼接会得到既非骨架也非叠加层的
+ * 第三种值；想改就该整份覆盖，语义可预测。
+ */
+export function deepMerge(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    const current = out[key];
+    out[key] =
+      isPlainObject(current) && isPlainObject(value)
+        ? deepMerge(current, value)
+        : value;
+  }
+  return out;
+}
+
+/** 只认「对象字面量语义」的普通对象：数组与 null 都不算 */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/registry/index.ts

@@ -0,0 +1,15 @@
+/** registry 域唯一出口：模板元数据定位 + npm 版本查询。 */
+export {
+  overlayDirOf,
+  readTemplateMeta,
+  resolveTemplateRoot,
+  OVERLAY_DIR,
+  type TemplateMeta,
+  type TemplateOption,
+} from "./template-meta.ts";
+export {
+  applyResolvedVersions,
+  fetchLatestVersion,
+  resolveVersions,
+  type ResolvedVersion,
+} from "./versions.ts";