cf-yoyo 1.0.0

package/src/core/template-engine.ts

@@ -0,0 +1,324 @@
+/**
+ * 模板引擎模組
+ * 負責模板的渲染、變數替換與條件渲染
+ *
+ * 使用 Mustache 語法：
+ * - {{variable}} - 變數替換
+ * - {{#condition}}...{{/condition}} - 條件渲染（條件為 truthy 時顯示）
+ * - {{^condition}}...{{/condition}} - 反向條件渲染（條件為 falsy 時顯示）
+ * - {{!comment}} - 註解（不輸出）
+ */
+
+import * as path from 'path';
+import {
+  TemplateContext,
+  TemplateConfig,
+  TemplateFile,
+  TemplateRenderResult,
+  RenderOptions,
+} from '../types';
+import { readFile, fileExists, createDirectory, writeFile } from './filesystem';
+import { logger } from '../utils/logger';
+
+/**
+ * 變數替換正則表達式
+ * 支援：{{variable}}、{{#condition}}、{{^condition}}、{{!comment}}
+ */
+const VARIABLE_REGEX = /\{\{([#^!]?)\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\}\}/g;
+
+/**
+ * 檔案名稱中的變數替換正則
+ * 例如：__projectName__.ts
+ */
+const FILENAME_VARIABLE_REGEX = /__([a-zA-Z_$][a-zA-Z0-9_$]*)__/g;
+
+/**
+ * 渲染模板字符串
+ * 支援變數替換與條件渲染
+ */
+export function renderTemplate(
+  template: string,
+  context: TemplateContext,
+  options?: RenderOptions
+): string {
+  const { escapeHtml = true } = options || {};
+
+  if (!template) {
+    return '';
+  }
+
+  let result = template;
+
+  // 處理條件區塊（支援巢狀）
+  // 先處理正向條件 {{#condition}}content{{/condition}}
+  result = renderSections(result, context, true);
+
+  // 處理反向條件 {{^condition}}content{{/condition}}
+  result = renderSections(result, context, false);
+
+  // 處理普通變數替換
+  result = result.replace(VARIABLE_REGEX, (match, prefix, name) => {
+    // 跳過條件和註解前綴
+    if (prefix === '#' || prefix === '^' || prefix === '!') {
+      return match;
+    }
+
+    const value = getNestedValue(context, name);
+    const stringValue = value !== undefined && value !== null ? String(value) : '';
+
+    return escapeHtml ? escapeHtmlEntities(stringValue) : stringValue;
+  });
+
+  return result;
+}
+
+/**
+ * 渲染條件區塊
+ * @param isSection - true 表示正向條件（{{#var}}），false 表示反向條件（{{^var}}）
+ */
+function renderSections(template: string, context: TemplateContext, isSection: boolean): string {
+  let result = template;
+  const regex = isSection
+    ? /\{\{#\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\}\}([\s\S]*?)\{\{\/\s*\1\s*\}\}/g
+    : /\{\{\^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\}\}([\s\S]*?)\{\{\/\s*\1\s*\}\}/g;
+
+  // 需要重複處理，因為可能存在巢狀
+  let lastResult = '';
+  let iterations = 0;
+  const MAX_ITERATIONS = 100; // 防止無限循環
+
+  while (result !== lastResult && iterations < MAX_ITERATIONS) {
+    lastResult = result;
+    iterations++;
+
+    result = result.replace(regex, (match, name, content) => {
+      const value = getNestedValue(context, name);
+      const isTruthy = isTruthyValue(value);
+
+      if (isSection) {
+        // 正向條件：值為 truthy 時顯示內容
+        return isTruthy ? content : '';
+      } else {
+        // 反向條件：值為 falsy 時顯示內容
+        return !isTruthy ? content : '';
+      }
+    });
+  }
+
+  return result;
+}
+
+/**
+ * 檢查值是否為 truthy
+ * 陣列會檢查長度，物件會檢查是否有鍵
+ */
+function isTruthyValue(value: unknown): boolean {
+  if (value === undefined || value === null) {
+    return false;
+  }
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return value !== 0;
+  }
+  if (typeof value === 'string') {
+    return value.length > 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.keys(value).length > 0;
+  }
+  return Boolean(value);
+}
+
+/**
+ * 獲取巢狀物件值
+ * 支援點號表示法，例如：user.name
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const keys = path.split('.');
+  let value: unknown = obj;
+
+  for (const key of keys) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    if (typeof value === 'object') {
+      value = (value as Record<string, unknown>)[key];
+    } else {
+      return undefined;
+    }
+  }
+
+  return value;
+}
+
+/**
+ * 轉義 HTML 實體
+ */
+function escapeHtmlEntities(text: string): string {
+  const htmlEntities: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+  };
+
+  return text.replace(/[&<>"']/g, (char) => htmlEntities[char] || char);
+}
+
+/**
+ * 處理檔案名稱中的變數替換
+ * 將 __variable__ 替換為實際值
+ */
+export function renderFileName(fileName: string, context: TemplateContext): string {
+  return fileName.replace(FILENAME_VARIABLE_REGEX, (match, name) => {
+    const value = getNestedValue(context, name);
+    return value !== undefined && value !== null ? String(value) : match;
+  });
+}
+
+/**
+ * 從模板配置生成完整的渲染結果
+ */
+export async function renderTemplateToFiles(
+  templateConfig: TemplateConfig,
+  targetDir: string,
+  context: TemplateContext
+): Promise<TemplateRenderResult> {
+  const result: TemplateRenderResult = {
+    success: true,
+    files: [],
+    errors: [],
+  };
+
+  logger.debug(`開始渲染模板：${templateConfig.name}`);
+  logger.debug(`目標目錄：${targetDir}`);
+  logger.debug(`渲染上下文：${JSON.stringify(context, null, 2)}`);
+
+  for (const file of templateConfig.files) {
+    try {
+      // 渲染目標路徑
+      const renderedPath = renderFileName(file.targetPath, context);
+      const fullTargetPath = path.join(targetDir, renderedPath);
+
+      // 確保目標目錄存在
+      const targetFileDir = path.dirname(fullTargetPath);
+      createDirectory(targetFileDir);
+
+      let content: string;
+
+      if (file.sourcePath) {
+        // 從檔案讀取模板
+        const templateContent = readFile(file.sourcePath);
+        if (templateContent === null) {
+          throw new Error(`無法讀取模板檔案：${file.sourcePath}`);
+        }
+        content = renderTemplate(templateContent, context, {
+          escapeHtml: false,
+        });
+      } else if (file.content) {
+        // 使用內嵌內容
+        content = renderTemplate(file.content, context, { escapeHtml: false });
+      } else {
+        throw new Error(`模板檔案 ${file.targetPath} 沒有來源內容`);
+      }
+
+      // 寫入檔案
+      if (writeFile(fullTargetPath, content, { overwrite: true })) {
+        result.files.push(fullTargetPath);
+        logger.debug(`已生成檔案：${fullTargetPath}`);
+      } else {
+        throw new Error(`無法寫入檔案：${fullTargetPath}`);
+      }
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      result.errors.push({
+        file: file.targetPath,
+        error: errorMessage,
+      });
+      logger.error(`渲染檔案失敗 ${file.targetPath}：${errorMessage}`);
+    }
+  }
+
+  if (result.errors.length > 0 && result.files.length === 0) {
+    result.success = false;
+  }
+
+  return result;
+}
+
+/**
+ * 驗證模板上下文
+ * 檢查是否包含所有必需的變數
+ */
+export function validateContext(
+  context: TemplateContext,
+  requiredVars: string[]
+): { valid: boolean; missing: string[] } {
+  const missing: string[] = [];
+
+  for (const varName of requiredVars) {
+    const value = getNestedValue(context, varName);
+    if (value === undefined || value === null) {
+      missing.push(varName);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+/**
+ * 生成預設的模板上下文
+ * 基於專案配置生成預設值
+ */
+export function generateDefaultContext(projectConfig: {
+  projectName: string;
+  projectType: string;
+  template: string;
+  language?: string;
+}): TemplateContext {
+  const now = new Date();
+
+  return {
+    projectName: projectConfig.projectName,
+    projectType: projectConfig.projectType,
+    template: projectConfig.template,
+    // 基本資訊
+    author: '', // 可由用戶提供或從 git 配置讀取
+    email: '',
+    description: `${projectConfig.projectName} - Cloudflare ${projectConfig.projectType} 專案`,
+    version: '1.0.0',
+    license: 'MIT',
+    // 時間戳
+    year: now.getFullYear(),
+    date: now.toISOString().split('T')[0] || '',
+    timestamp: now.toISOString(),
+    // Cloudflare 相關
+    isWorker: projectConfig.projectType === 'worker' || projectConfig.projectType === 'hono',
+    isPages: projectConfig.projectType === 'pages',
+    isD1: projectConfig.projectType === 'd1',
+    isKV: projectConfig.projectType === 'kv',
+    isR2: projectConfig.projectType === 'r2',
+    // 框架相關
+    isHono: projectConfig.template === 'hono',
+    isReact: projectConfig.template === 'react',
+    isVue: projectConfig.template === 'vue',
+    isNextjs: projectConfig.template === 'nextjs',
+  };
+}
+
+export default {
+  renderTemplate,
+  renderFileName,
+  renderTemplateToFiles,
+  validateContext,
+  generateDefaultContext,
+};

package/src/core/template-manager.ts

@@ -0,0 +1,338 @@
+/**
+ * 模板管理器模組
+ * 負責模板的載入、查找與驗證
+ */
+
+import * as path from 'path';
+import {
+  TemplateConfig,
+  TemplateInfo,
+  ProjectType,
+  TemplateType,
+  TemplateFile,
+  Language,
+} from '../types';
+import { directoryExists, readFile, listDirectory, fileExists } from './filesystem';
+import { logger } from '../utils/logger';
+
+/**
+ * 模板基礎路徑
+ * 指向專案中的 templates 目錄
+ */
+const TEMPLATES_BASE_PATH = path.join(__dirname, '../../templates');
+
+/**
+ * 模板配置檔名稱
+ */
+const TEMPLATE_CONFIG_FILE = 'template.json';
+
+/**
+ * 可用的模板類型映射
+ * 根據專案類型和語言分類
+ */
+const AVAILABLE_TEMPLATES: Record<
+  ProjectType,
+  Record<Language, Array<{ type: TemplateType; name: string; description: string }>>
+> = {
+  [ProjectType.WORKER]: {
+    [Language.TYPESCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: '基礎 Worker',
+        description: '最簡單的 Cloudflare Worker 專案，使用原生 API',
+      },
+      {
+        type: TemplateType.HONO,
+        name: 'Hono Worker',
+        description: '使用 Hono 框架的 Cloudflare Worker 專案',
+      },
+      {
+        type: TemplateType.ITTY_ROUTER,
+        name: 'itty-router Worker',
+        description: '使用 itty-router 路由庫的 Worker 專案',
+      },
+    ],
+    [Language.JAVASCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: '基礎 Worker (JavaScript)',
+        description: '最簡單的 Cloudflare Worker 專案，使用原生 API',
+      },
+      {
+        type: TemplateType.HONO,
+        name: 'Hono Worker (JavaScript)',
+        description: '使用 Hono 框架的 Cloudflare Worker 專案',
+      },
+    ],
+  },
+  [ProjectType.PAGES]: {
+    [Language.TYPESCRIPT]: [
+      {
+        type: TemplateType.STATIC,
+        name: '靜態網站',
+        description: '純靜態 HTML/CSS/JS 的 Pages 專案',
+      },
+      {
+        type: TemplateType.REACT,
+        name: 'React Pages',
+        description: '使用 React 的 Pages 專案',
+      },
+      {
+        type: TemplateType.VUE,
+        name: 'Vue Pages',
+        description: '使用 Vue 的 Pages 專案',
+      },
+      {
+        type: TemplateType.NEXTJS,
+        name: 'Next.js Pages',
+        description: '使用 Next.js 的 Pages 專案',
+      },
+    ],
+    [Language.JAVASCRIPT]: [
+      {
+        type: TemplateType.STATIC,
+        name: '靜態網站 (JavaScript)',
+        description: '純靜態 HTML/CSS/JS 的 Pages 專案',
+      },
+    ],
+  },
+  [ProjectType.D1]: {
+    [Language.TYPESCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'D1 基礎模板',
+        description: '整合 Cloudflare D1 資料庫的 Worker 專案',
+      },
+    ],
+    [Language.JAVASCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'D1 基礎模板 (JavaScript)',
+        description: '整合 Cloudflare D1 資料庫的 Worker 專案',
+      },
+    ],
+  },
+  [ProjectType.KV]: {
+    [Language.TYPESCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'KV 基礎模板',
+        description: '整合 Cloudflare KV 存儲的 Worker 專案',
+      },
+    ],
+    [Language.JAVASCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'KV 基礎模板 (JavaScript)',
+        description: '整合 Cloudflare KV 存儲的 Worker 專案',
+      },
+    ],
+  },
+  [ProjectType.R2]: {
+    [Language.TYPESCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'R2 基礎模板',
+        description: '整合 Cloudflare R2 存儲的 Worker 專案',
+      },
+    ],
+    [Language.JAVASCRIPT]: [
+      {
+        type: TemplateType.BASIC,
+        name: 'R2 基礎模板 (JavaScript)',
+        description: '整合 Cloudflare R2 存儲的 Worker 專案',
+      },
+    ],
+  },
+};
+
+/**
+ * 獲取指定專案類型和語言的可用模板
+ */
+export function getTemplatesForProjectType(
+  projectType: ProjectType,
+  language: Language = Language.TYPESCRIPT
+): Array<{ type: TemplateType; name: string; description: string }> {
+  return AVAILABLE_TEMPLATES[projectType]?.[language] || [];
+}
+
+/**
+ * 獲取所有可用的模板資訊
+ * 包含所有語言和專案類型的模板
+ */
+export function getAllTemplates(): TemplateInfo[] {
+  const templates: TemplateInfo[] = [];
+
+  for (const [projectType, langTemplates] of Object.entries(AVAILABLE_TEMPLATES)) {
+    for (const [language, templateList] of Object.entries(langTemplates)) {
+      for (const template of templateList) {
+        templates.push({
+          id: `${projectType}-${language}-${template.type}`,
+          name: template.name,
+          description: template.description,
+          projectType: projectType as ProjectType,
+          language: language as Language,
+          path: getTemplatePath(projectType as ProjectType, template.type, language as Language),
+        });
+      }
+    }
+  }
+
+  return templates;
+}
+
+/**
+ * 獲取模板路徑
+ * 根據專案類型、模板類型和語言構建路徑
+ */
+export function getTemplatePath(
+  projectType: ProjectType,
+  templateType: TemplateType,
+  language: Language = Language.TYPESCRIPT
+): string {
+  // JS 模板使用 -js 後綴區分
+  const langSuffix = language === Language.JAVASCRIPT ? '-js' : '';
+  return path.join(TEMPLATES_BASE_PATH, projectType, `${templateType}${langSuffix}`);
+}
+
+/**
+ * 驗證模板是否存在且完整
+ */
+export function validateTemplate(
+  projectType: ProjectType,
+  templateType: TemplateType,
+  language: Language = Language.TYPESCRIPT
+): { valid: boolean; error?: string } {
+  const templatePath = getTemplatePath(projectType, templateType, language);
+
+  // 檢查模板目錄是否存在
+  if (!directoryExists(templatePath)) {
+    return {
+      valid: false,
+      error: `模板目錄不存在：${templatePath}`,
+    };
+  }
+
+  // 檢查模板配置檔
+  const configPath = path.join(templatePath, TEMPLATE_CONFIG_FILE);
+  if (!fileExists(configPath)) {
+    return {
+      valid: false,
+      error: `模板配置檔不存在：${configPath}`,
+    };
+  }
+
+  // 嘗試解析配置
+  try {
+    const configContent = readFile(configPath);
+    if (!configContent) {
+      return {
+        valid: false,
+        error: `無法讀取模板配置檔：${configPath}`,
+      };
+    }
+
+    const config = JSON.parse(configContent) as TemplateConfig;
+
+    // 檢查必需的檔案是否存在
+    for (const file of config.files) {
+      if (file.sourcePath) {
+        const fullSourcePath = path.join(templatePath, file.sourcePath);
+        if (!fileExists(fullSourcePath)) {
+          return {
+            valid: false,
+            error: `模板檔案不存在：${fullSourcePath}`,
+          };
+        }
+      }
+    }
+
+    return { valid: true };
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      valid: false,
+      error: `模板配置檔解析失敗：${errorMessage}`,
+    };
+  }
+}
+
+/**
+ * 載入模板配置
+ */
+export function loadTemplate(
+  projectType: ProjectType,
+  templateType: TemplateType,
+  language: Language = Language.TYPESCRIPT
+): TemplateConfig | null {
+  const templatePath = getTemplatePath(projectType, templateType, language);
+  const configPath = path.join(templatePath, TEMPLATE_CONFIG_FILE);
+
+  try {
+    if (!fileExists(configPath)) {
+      logger.error(`模板配置檔不存在：${configPath}`);
+      return null;
+    }
+
+    const configContent = readFile(configPath);
+    if (!configContent) {
+      logger.error(`無法讀取模板配置檔：${configPath}`);
+      return null;
+    }
+
+    const config = JSON.parse(configContent) as TemplateConfig;
+
+    // 解析檔案的完整路徑
+    config.files = config.files.map((file: TemplateFile) => ({
+      ...file,
+      sourcePath: file.sourcePath ? path.join(templatePath, file.sourcePath) : undefined,
+    }));
+
+    logger.debug(`已載入模板：${config.name}`);
+    return config;
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`載入模板失敗：${errorMessage}`);
+    return null;
+  }
+}
+
+/**
+ * 獲取預設模板類型
+ * 根據專案類型返回預設的模板
+ */
+export function getDefaultTemplateType(projectType: ProjectType): TemplateType {
+  switch (projectType) {
+    case ProjectType.WORKER:
+      return TemplateType.BASIC;
+    case ProjectType.PAGES:
+      return TemplateType.STATIC;
+    case ProjectType.D1:
+    case ProjectType.KV:
+    case ProjectType.R2:
+      return TemplateType.BASIC;
+    default:
+      return TemplateType.BASIC;
+  }
+}
+
+/**
+ * 檢查模板類型是否適用於指定專案類型
+ */
+export function isTemplateCompatible(
+  projectType: ProjectType,
+  templateType: TemplateType
+): boolean {
+  const templates = getTemplatesForProjectType(projectType);
+  return templates.some((t) => t.type === templateType);
+}
+
+export default {
+  getTemplatesForProjectType,
+  getAllTemplates,
+  getTemplatePath,
+  validateTemplate,
+  loadTemplate,
+  getDefaultTemplateType,
+  isTemplateCompatible,
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+/**
+ * create-cf-project CLI 工具主入口
+ *
+ * 使用方式：
+ *   npx create-cf-project create [project-name] [options]
+ *   npx create-cf-project list
+ *
+ * @packageDocumentation
+ */
+
+import { runCLI } from './cli';
+
+// 執行 CLI
+runCLI().catch((error) => {
+  console.error('執行 CLI 時發生錯誤:', error);
+  process.exit(1);
+});