@longzai-intelligence-templates/template-engine 0.0.5

package/src/generator.service.ts

@@ -0,0 +1,150 @@
+/**
+ * 文件生成器
+ *
+ * 将模板文件渲染到目标目录
+ */
+
+import type { TemplateFile, TemplateMeta } from './template.schema';
+
+import { replaceVariables, resolveDestinationPath, type VariableValues } from './engine.utils';
+import { readTemplateFile } from './loader.service';
+
+/**
+ * 生成结果项
+ */
+export type GeneratedFile = {
+  /**
+   * 目标文件路径
+   */
+  destination: string;
+
+  /**
+   * 是否跳过（条件不满足）
+   */
+  skipped: boolean;
+
+  /**
+   * 是否为可执行文件
+   */
+  executable: boolean;
+};
+
+/**
+ * 预览将要生成的文件列表
+ *
+ * @param meta - 模板元数据
+ * @param variables - 变量值映射
+ * @returns 生成结果预览
+ */
+export const previewGeneration = (
+  meta: TemplateMeta,
+  variables: VariableValues,
+): GeneratedFile[] => {
+  return meta.files.map((file) => {
+    /**
+     * 该文件的生成条件是否满足
+     */
+    const conditionMet = checkCondition(file, variables);
+
+    /**
+     * 变量替换后的目标文件路径
+     */
+    const destination = resolveDestinationPath(file.destination, variables);
+
+    return {
+      destination,
+      skipped: !conditionMet,
+      executable: file.executable,
+    };
+  });
+};
+
+/**
+ * 检查文件的条件是否满足
+ *
+ * @param file - 模板文件定义
+ * @param variables - 变量值映射
+ * @returns 条件是否满足
+ */
+const checkCondition = (file: TemplateFile, variables: VariableValues): boolean => {
+  if (!file.condition) {
+    return true;
+  }
+
+  /**
+   * 条件变量对应的值，真值时保留该文件
+   */
+  const value = variables[file.condition];
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return value !== '' && value !== 'false';
+  }
+  return false;
+};
+
+/**
+ * 生成模板文件到目标目录
+ *
+ * @param templateDir - 模板目录路径
+ * @param meta - 模板元数据
+ * @param variables - 变量值映射
+ * @param outputDir - 输出目录路径
+ * @param dryRun - 是否仅预览
+ * @returns 生成的文件列表
+ */
+export const generateFiles = async (
+  templateDir: string,
+  meta: TemplateMeta,
+  variables: VariableValues,
+  outputDir: string,
+  dryRun: boolean = false,
+): Promise<GeneratedFile[]> => {
+  /**
+   * 每个模板文件的处理结果集合
+   */
+  const results: GeneratedFile[] = [];
+
+  for (const file of meta.files) {
+    /**
+     * 该文件的生成条件是否满足
+     */
+    const conditionMet = checkCondition(file, variables);
+
+    /**
+     * 变量替换后的目标文件路径
+     */
+    const destination = resolveDestinationPath(file.destination, variables);
+
+    if (!conditionMet) {
+      results.push({ destination, skipped: true, executable: file.executable });
+      continue;
+    }
+
+    if (dryRun) {
+      results.push({ destination, skipped: false, executable: file.executable });
+      continue;
+    }
+
+    /**
+     * 读取模板文件内容
+     */
+    const content = await readTemplateFile(templateDir, file.source);
+
+    /**
+     * 替换变量
+     */
+    const rendered = replaceVariables(content, variables);
+
+    /**
+     * 写入目标文件
+     */
+    const fullPath = `${outputDir}/${destination}`;
+    await Bun.write(fullPath, rendered);
+
+    results.push({ destination, skipped: false, executable: file.executable });
+  }
+
+  return results;
+};

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @longzai-intelligence-templates/template-engine
+ *
+ *   模板引擎核心包，提供模板变量替换、文件生成和模板加载功能。
+ */
+
+export {
+  TemplateMetaSchema,
+  TemplateVariableSchema,
+  TemplateFileSchema,
+  BUILTIN_VARIABLES,
+  type TemplateMeta,
+  type TemplateCategory,
+  type VariableType,
+  type TemplateVariable,
+  type TemplateFile,
+  type BuiltinVariable,
+} from './template.schema';
+
+export {
+  replaceVariables,
+  parseVariableValue,
+  validateVariable,
+  buildBuiltinVariables,
+  mergeVariableValues,
+  resolveDestinationPath,
+  type VariableValues,
+} from './engine.utils';
+
+export {
+  loadTemplateMeta,
+  loadAllTemplates,
+  readTemplateFile,
+  filterByCategory,
+  searchTemplates,
+  findTemplateById,
+} from './loader.service';
+
+export { previewGeneration, generateFiles, type GeneratedFile } from './generator.service';

package/src/loader.service.ts

@@ -0,0 +1,185 @@
+/**
+ * 模板加载器
+ *
+ * 从文件系统加载模板定义和模板文件
+ */
+
+import { existsSync } from 'node:fs';
+
+import { type TemplateMeta, TemplateMetaSchema } from './template.schema';
+
+/**
+ * 从目录加载模板元数据
+ *
+ * @param templateDir - 模板目录路径
+ * @returns 模板元数据
+ * @throws {@link Error} 元数据文件内容未通过 Schema 校验时抛出（含校验错误详情）
+ */
+export const loadTemplateMeta = async (templateDir: string): Promise<TemplateMeta> => {
+  /**
+   * 模板元数据文件路径，固定为目录下的 template.json
+   */
+  const metaPath = `${templateDir}/template.json`;
+
+  /**
+   * 元数据文件句柄
+   */
+  const file = Bun.file(metaPath);
+
+  /**
+   * 解析后的元数据 JSON 内容
+   */
+  const content = await file.json();
+
+  /**
+   * Schema 校验结果，失败时抛出携带校验详情的错误
+   */
+  const parsed = TemplateMetaSchema.safeParse(content);
+  if (!parsed.success) {
+    throw new Error(`模板元数据校验失败（${metaPath}）: ${parsed.error.message}`);
+  }
+  return parsed.data;
+};
+
+/**
+ * 加载目录下所有模板的元数据
+ *
+ * @param templatesRoot - 模板根目录路径
+ * @returns 模板元数据数组
+ */
+export const loadAllTemplates = async (templatesRoot: string): Promise<TemplateMeta[]> => {
+  /**
+   * 模板分类目录名列表，与模板仓库的目录划分一一对应
+   */
+  const categories = ['projects', 'apps', 'packages', 'domains', 'configs', 'docs', 'adapters'];
+
+  /**
+   * 收集到的全部模板元数据
+   */
+  const templates: TemplateMeta[] = [];
+
+  for (const category of categories) {
+    /**
+     * 当前分类目录的完整路径
+     */
+    const categoryDir = `${templatesRoot}/${category}`;
+
+    /**
+     * 分类目录存在性，缺失的分类静默跳过
+     */
+    const categoryExists = existsSync(categoryDir);
+    if (!categoryExists) {
+      continue;
+    }
+
+    /**
+     * 扫描分类目录下子目录用的 glob 匹配器
+     */
+    const glob = new Bun.Glob('*');
+
+    for await (const dir of glob.scan({ cwd: categoryDir, onlyFiles: false })) {
+      /**
+       * 当前候选模板的元数据文件路径
+       */
+      const metaPath = `${categoryDir}/${dir}/template.json`;
+      try {
+        /**
+         * 候选元数据文件句柄
+         */
+        const file = Bun.file(metaPath);
+        if (await file.exists()) {
+          /**
+           * 解析后的元数据 JSON 内容
+           */
+          const content = await file.json();
+
+          /**
+           * Schema 校验结果，未通过的模板静默跳过
+           */
+          const parsed = TemplateMetaSchema.safeParse(content);
+          if (parsed.success) {
+            templates.push(parsed.data);
+          }
+        }
+      } catch {
+        /**
+         * 跳过无法加载的模板
+         */
+      }
+    }
+  }
+
+  return templates;
+};
+
+/**
+ * 读取模板文件内容
+ *
+ * @param templateDir - 模板目录路径
+ * @param sourcePath - 源文件路径（相对于模板目录）
+ * @returns 文件内容字符串
+ */
+export const readTemplateFile = async (
+  templateDir: string,
+  sourcePath: string,
+): Promise<string> => {
+  /**
+   * 模板源文件的完整路径
+   */
+  const filePath = `${templateDir}/${sourcePath}`;
+
+  /**
+   * 模板源文件句柄
+   */
+  const file = Bun.file(filePath);
+  return await file.text();
+};
+
+/**
+ * 按分类过滤模板
+ *
+ * @param templates - 模板列表
+ * @param category - 分类名称
+ * @returns 过滤后的模板列表
+ */
+export const filterByCategory = (templates: TemplateMeta[], category?: string): TemplateMeta[] => {
+  if (!category) {
+    return templates;
+  }
+  return templates.filter((t) => t.category === category);
+};
+
+/**
+ * 按关键词搜索模板
+ *
+ * @param templates - 模板列表
+ * @param keyword - 搜索关键词
+ * @returns 匹配的模板列表
+ */
+export const searchTemplates = (templates: TemplateMeta[], keyword: string): TemplateMeta[] => {
+  /**
+   * 小写化后的搜索关键词，用于大小写不敏感匹配
+   */
+  const lowerKeyword = keyword.toLowerCase();
+  return templates.filter((t) => {
+    return (
+      t.name.toLowerCase().includes(lowerKeyword) ||
+      t.description.toLowerCase().includes(lowerKeyword) ||
+      t.tags.some((tag) => tag.toLowerCase().includes(lowerKeyword))
+    );
+  });
+};
+
+/**
+ * 根据 ID 查找模板
+ *
+ * @param templates - 模板列表
+ * @param id - 模板 ID
+ * @returns 模板元数据或 undefined
+ */
+export const findTemplateById = (
+  templates: TemplateMeta[],
+  id: string,
+): TemplateMeta | undefined => {
+  return templates.find((t) => t.id === id);
+};

package/src/template.schema.ts

@@ -0,0 +1,194 @@
+/**
+ * 模板元数据 Schema 定义
+ *
+ * 定义模板的元数据结构，包括分类、变量、文件列表等
+ */
+
+import * as z from 'zod';
+
+/**
+ * 模板分类枚举 Schema
+ */
+export const TemplateCategorySchema = z.enum([
+  'project',
+  'app',
+  'package',
+  'domain',
+  'config',
+  'docs',
+  'adapter',
+]);
+
+/**
+ * 模板分类类型
+ */
+export type TemplateCategory = z.infer<typeof TemplateCategorySchema>;
+
+/**
+ * 模板变量类型枚举 Schema
+ */
+export const VariableTypeSchema = z.enum(['string', 'boolean', 'select']);
+
+/**
+ * 模板变量类型
+ */
+export type VariableType = z.infer<typeof VariableTypeSchema>;
+
+/**
+ * 模板变量定义 Schema
+ */
+export const TemplateVariableSchema = z.object({
+  /**
+   * 变量名称
+   */
+  name: z.string(),
+
+  /**
+   * 变量类型
+   */
+  type: VariableTypeSchema,
+
+  /**
+   * 变量的用途说明，展示给用户辅助填写
+   */
+  description: z.string(),
+
+  /**
+   * 默认值
+   */
+  defaultValue: z.string().optional(),
+
+  /**
+   * 是否必填
+   */
+  required: z.boolean().default(true),
+
+  /**
+   * select 类型的选项列表
+   */
+  options: z
+    .array(
+      z.object({
+        label: z.string(),
+        value: z.string(),
+      }),
+    )
+    .optional(),
+
+  /**
+   * 验证正则
+   */
+  pattern: z.string().optional(),
+
+  /**
+   * 验证失败提示
+   */
+  patternMessage: z.string().optional(),
+});
+
+/**
+ * 模板变量定义类型
+ */
+export type TemplateVariable = z.infer<typeof TemplateVariableSchema>;
+
+/**
+ * 模板文件定义 Schema
+ */
+export const TemplateFileSchema = z.object({
+  /**
+   * 模板源文件路径（相对于模板目录）
+   */
+  source: z.string(),
+
+  /**
+   * 目标文件路径模板（支持变量替换）
+   */
+  destination: z.string(),
+
+  /**
+   * 是否为可执行文件
+   */
+  executable: z.boolean().default(false),
+
+  /**
+   * 条件变量（仅当该变量为真时生成此文件）
+   */
+  condition: z.string().optional(),
+});
+
+/**
+ * 模板文件定义类型
+ */
+export type TemplateFile = z.infer<typeof TemplateFileSchema>;
+
+/**
+ * 模板元数据 Schema
+ */
+export const TemplateMetaSchema = z.object({
+  /**
+   * 模板唯一标识（kebab-case）
+   */
+  id: z.string(),
+
+  /**
+   * 模板显示名称
+   */
+  name: z.string(),
+
+  /**
+   * 模板描述
+   */
+  description: z.string(),
+
+  /**
+   * 所属分类
+   */
+  category: TemplateCategorySchema,
+
+  /**
+   * 标签列表
+   */
+  tags: z.array(z.string()).default([]),
+
+  /**
+   * 模板变量定义
+   */
+  variables: z.array(TemplateVariableSchema).default([]),
+
+  /**
+   * 模板文件列表
+   */
+  files: z.array(TemplateFileSchema).default([]),
+
+  /**
+   * 依赖的其他模板 ID
+   */
+  dependencies: z.array(z.string()).default([]),
+
+  /**
+   * 模板版本
+   */
+  version: z.string().default('0.1.0'),
+});
+
+/**
+ * 模板元数据类型
+ */
+export type TemplateMeta = z.infer<typeof TemplateMetaSchema>;
+
+/**
+ * 内置变量名称常量
+ */
+export const BUILTIN_VARIABLES = {
+  projectName: 'projectName',
+  projectScope: 'projectScope',
+  domainName: 'domainName',
+  packageName: 'packageName',
+  author: 'author',
+  year: 'year',
+} as const;
+
+/**
+ * 内置变量类型
+ */
+export type BuiltinVariable = keyof typeof BUILTIN_VARIABLES;