@justin_666/square-couplets-master-skills 1.0.3 → 1.0.5

package/skills/generate-doufang-prompt/index.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+/**
+ * Executable script for generate-doufang-prompt skill
+ * Can be called directly by agents or users
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { execSync } from 'child_process';
+import { createRequire } from 'module';
+
+// Load environment variables helper
+async function loadEnvironmentVariables() {
+  try {
+    const dotenv = await import('dotenv');
+    const envLocalPath = join(projectRoot, '.env.local');
+    const envPath = join(projectRoot, '.env');
+    const cwdEnvLocalPath = join(process.cwd(), '.env.local');
+    const cwdEnvPath = join(process.cwd(), '.env');
+
+    if (existsSync(envLocalPath)) {
+      dotenv.config({ path: envLocalPath });
+    } else if (existsSync(envPath)) {
+      dotenv.config({ path: envPath });
+    } else if (existsSync(cwdEnvLocalPath)) {
+      dotenv.config({ path: cwdEnvLocalPath });
+    } else if (existsSync(cwdEnvPath)) {
+      dotenv.config({ path: cwdEnvPath });
+    } else {
+      dotenv.config();
+    }
+  } catch (e) {
+    // dotenv not available, continue without it (will use environment variables)
+  }
+}
+
+// Resolve project root and service path
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillDir = resolve(__dirname);
+const projectRoot = resolve(skillDir, '../..');
+
+// Try to find services directory
+function findServicesPath() {
+  // Get npm global prefix to find globally installed packages
+  let globalPrefix = null;
+  try {
+    globalPrefix = execSync('npm config get prefix', { encoding: 'utf-8' }).trim();
+  } catch (e) {
+    // Ignore error, try other methods
+  }
+  
+  // Try to resolve package location using createRequire (works in ES modules)
+  let packageRoot = null;
+  try {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('@justin_666/square-couplets-master-skills/package.json');
+    packageRoot = dirname(packageJsonPath);
+  } catch (e) {
+    // Package not found via require.resolve, will try other paths
+  }
+  
+  const possiblePaths = [
+    // Global npm package (highest priority - most reliable for installed packages)
+    ...(globalPrefix ? [
+      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+    ] : []),
+    // From resolved package root (if it has services)
+    ...(packageRoot ? [join(packageRoot, 'services')] : []),
+    // Local project root
+    join(projectRoot, 'services'),
+    // Local node_modules
+    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+    // Current working directory
+    join(process.cwd(), 'services'),
+    // Current working directory node_modules
+    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+  ];
+
+  // Debug: log all paths being checked (only in development)
+  if (process.env.DEBUG_DOUFANG) {
+    console.log('🔍 Checking paths for services directory:');
+    for (const path of possiblePaths) {
+      console.log(`   - ${path} ${existsSync(path) ? '✅' : '❌'}`);
+    }
+  }
+  
+  for (const path of possiblePaths) {
+    try {
+      if (statSync(path).isDirectory()) {
+        if (process.env.DEBUG_DOUFANG) {
+          console.log(`✅ Found services at: ${path}`);
+        }
+        return path;
+      }
+    } catch (e) {
+      // Path doesn't exist, try next
+    }
+  }
+  
+  // If not found, provide helpful error message
+  if (process.env.DEBUG_DOUFANG) {
+    console.log('❌ Services directory not found in any of the checked paths');
+  }
+  return null;
+}
+
+
+async function main() {
+  try {
+    // Load environment variables first
+    await loadEnvironmentVariables();
+    
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const keyword = args[0];
+    const referenceImagePath = args[1]; // Optional reference image path
+    
+    if (!keyword) {
+      console.error('❌ Error: Keyword is required');
+      console.log('\nUsage:');
+      console.log('  node skills/generate-doufang-prompt/index.js <keyword> [reference-image-path]');
+      console.log('\nExample:');
+      console.log('  node skills/generate-doufang-prompt/index.js "財富"');
+      console.log('  node skills/generate-doufang-prompt/index.js "健康" images/reference.png');
+      process.exit(1);
+    }
+
+    // Get API key
+    const apiKey = process.env.GEMINI_API_KEY || process.env.API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+    
+    if (!apiKey) {
+      console.error('❌ Error: API Key is missing');
+      console.log('💡 Set GEMINI_API_KEY in .env file or environment variable');
+      process.exit(1);
+    }
+
+    // Try to import service function
+    const servicesPath = findServicesPath();
+    if (!servicesPath) {
+      console.error('❌ Error: Cannot find services directory');
+      console.log('💡 Make sure you are running from the project root or have installed the package');
+      process.exit(1);
+    }
+
+    // Dynamic import of service (support both .ts and .js)
+    let serviceModule;
+    try {
+      // Try .js first (for compiled npm package)
+      serviceModule = await import(`file://${join(servicesPath, 'geminiService.js')}`);
+    } catch (e) {
+      try {
+        // Try .ts (for development or source packages)
+        // Node.js cannot directly import .ts files
+        console.error('❌ Error: Cannot import TypeScript service module');
+        console.error('   The package contains TypeScript source files (.ts) which cannot be directly executed');
+        console.error('');
+        console.error('💡 Solution: Use the CLI command instead (recommended):');
+        console.error(`   doufang-prompt "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
+        console.error('');
+        console.error('   Or if you need to use the script directly:');
+        console.error('   1. Install tsx: npm install -g tsx');
+        console.error(`   2. Run: tsx skills/generate-doufang-prompt/index.js "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
+        process.exit(1);
+      } catch (e2) {
+        console.error('❌ Error: Cannot import service module');
+        console.error('   Tried:', join(servicesPath, 'geminiService.js'));
+        console.error('   Tried:', join(servicesPath, 'geminiService.ts'));
+        console.error('   💡 Solution: Use the CLI command instead:');
+        console.error(`      doufang-prompt "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
+        process.exit(1);
+      }
+    }
+    const { generateDoufangPrompt } = serviceModule;
+
+    // Load reference image if provided
+    let referenceImageDataUrl = null;
+    if (referenceImagePath) {
+      const fullPath = resolve(process.cwd(), referenceImagePath);
+      if (!existsSync(fullPath)) {
+        console.error(`❌ Error: Reference image not found: ${fullPath}`);
+        process.exit(1);
+      }
+      
+      const imageBuffer = readFileSync(fullPath);
+      const base64 = imageBuffer.toString('base64');
+      const ext = referenceImagePath.split('.').pop()?.toLowerCase();
+      const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
+      referenceImageDataUrl = `data:${mimeType};base64,${base64}`;
+    }
+
+    // Generate prompt
+    console.log(`📝 Generating prompt for keyword: "${keyword}"`);
+    if (referenceImagePath) {
+      console.log(`🖼️  Using reference image: ${referenceImagePath}`);
+    }
+    
+    const result = await generateDoufangPrompt(keyword, apiKey, referenceImageDataUrl);
+    
+    // Output as JSON
+    console.log(JSON.stringify(result, null, 2));
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/skills/optimize-doufang-prompt/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Executable script for optimize-doufang-prompt skill
+ * Optimizes prompts to reduce white margins and improve composition
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { existsSync, statSync } from 'fs';
+import { config } from 'dotenv';
+
+// Resolve project root
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillDir = resolve(__dirname);
+const projectRoot = resolve(skillDir, '../..');
+
+// Load environment variables
+const envLocalPath = join(projectRoot, '.env.local');
+const envPath = join(projectRoot, '.env');
+
+if (existsSync(envLocalPath)) {
+  config({ path: envLocalPath });
+} else if (existsSync(envPath)) {
+  config({ path: envPath });
+} else {
+  config();
+}
+
+async function optimizePrompt(originalPrompt) {
+  // This is a simple optimization - in a real implementation,
+  // you might want to use an LLM to optimize the prompt
+  
+  let optimized = originalPrompt;
+  
+  // Replace wide margin descriptions with minimal margin
+  optimized = optimized.replace(/wide\s+white\s+margins/gi, 'minimal elegant margins (2-5% of frame width)');
+  optimized = optimized.replace(/wide\s+margins/gi, 'minimal margins (2-5%)');
+  optimized = optimized.replace(/excessive\s+white\s+space/gi, 'minimal white space');
+  
+  // Ensure Doufang fills 85-95% of frame
+  if (!optimized.includes('85-95%')) {
+    optimized = optimized.replace(
+      /(Composition:.*?)(\.|$)/i,
+      (match, p1, p2) => {
+        if (!p1.includes('85-95%')) {
+          return p1 + ' The Doufang should fill 85-95% of the image area, maximizing visual impact.' + p2;
+        }
+        return match;
+      }
+    );
+  }
+  
+  // Add explicit margin requirements if not present
+  if (!optimized.includes('2-5%')) {
+    optimized += '\n\nIMPORTANT: The diamond-shaped Doufang must fill 85-95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins.';
+  }
+  
+  return optimized;
+}
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const prompt = args[0];
+    
+    if (!prompt) {
+      console.error('❌ Error: Prompt is required');
+      console.log('\nUsage:');
+      console.log('  node skills/optimize-doufang-prompt/index.js <prompt>');
+      console.log('\nOr pipe prompt:');
+      console.log('  echo "A diamond-shaped..." | node skills/optimize-doufang-prompt/index.js');
+      console.log('\nExample:');
+      console.log('  node skills/optimize-doufang-prompt/index.js "A diamond-shaped Doufang with wide white margins..."');
+      process.exit(1);
+    }
+
+    // Optimize prompt
+    console.log('✨ Optimizing prompt...\n');
+    const optimized = await optimizePrompt(prompt);
+    
+    // Output optimized prompt
+    console.log('✅ Optimized prompt:');
+    console.log('─'.repeat(60));
+    console.log(optimized);
+    console.log('─'.repeat(60));
+    
+    // Also output as JSON for programmatic use
+    console.log('\n📋 JSON output:');
+    console.log(JSON.stringify({ optimizedPrompt: optimized }, null, 2));
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/types.ts

@@ -0,0 +1,70 @@
+export interface GenerationResult {
+  keyword: string;
+  generatedPrompt: string;
+  imageUrl?: string;
+  blessingPhrase?: string;
+}
+
+export interface LoadingState {
+  isGeneratingPrompt: boolean;
+  isGeneratingImage: boolean;
+}
+
+export enum GenerationStatus {
+  IDLE = 'IDLE',
+  PROCESSING_PROMPT = 'PROCESSING_PROMPT',
+  PROCESSING_IMAGE = 'PROCESSING_IMAGE',
+  COMPLETED = 'COMPLETED',
+  ERROR = 'ERROR'
+}
+
+// API Types
+export interface GeminiResponse {
+  text?: string;
+  candidates?: Array<{
+    content?: {
+      parts?: Array<{
+        text?: string;
+        inlineData?: {
+          mimeType: string;
+          data: string;
+        };
+      }>;
+    };
+  }>;
+}
+
+export interface ApiError {
+  status?: number;
+  message?: string;
+  code?: string;
+}
+
+// Settings Types
+export interface AppSettings {
+  apiKey: string;
+  imageModel: 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview';
+  imageSize: '1K' | '2K' | '4K';
+}
+
+// Result Types
+export interface GenerationResultData {
+  prompt: string;
+  blessingPhrase: string;
+  imageUrl: string;
+}
+
+// Gemini API Types
+export interface GeminiContentPart {
+  text?: string;
+  inlineData?: {
+    mimeType: string;
+    data: string;
+  };
+}
+
+// Error Types
+export type ApiErrorInput = 
+  | { status?: number; message?: string; code?: string }
+  | Error
+  | unknown;

package/utils/errorHandler.ts

@@ -0,0 +1,123 @@
+import type { ApiErrorInput } from "../types";
+
+/**
+ * Custom error class for application errors
+ */
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public userMessage: string,
+    public recoverable: boolean = false,
+    public originalError?: unknown
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Object.setPrototypeOf(this, AppError.prototype);
+  }
+}
+
+/**
+ * Handle API errors and convert them to AppError
+ */
+export const handleApiError = (error: ApiErrorInput, context?: string): AppError => {
+  // Log error for debugging
+  console.error(`API Error${context ? ` in ${context}` : ''}:`, error);
+
+  // Extract error properties safely
+  const errorObj = error && typeof error === 'object' ? error as { status?: number; message?: string; code?: string } : null;
+  const status = errorObj?.status;
+  const message = errorObj?.message || (error instanceof Error ? error.message : String(error));
+
+  // Handle 400 errors - Invalid Request
+  if (status === 400 || message?.includes('400') || message?.includes('INVALID_ARGUMENT')) {
+    if (message?.includes('image') || message?.includes('format') || message?.includes('mime')) {
+      return new AppError(
+        message || 'Invalid image format',
+        'INVALID_IMAGE_FORMAT',
+        '圖片格式不支援，請嘗試其他圖片（建議使用 JPG 或 PNG）',
+        true,
+        error
+      );
+    }
+    return new AppError(
+      message || 'Invalid request',
+      'INVALID_REQUEST',
+      '請求格式不正確，請檢查設置',
+      true,
+      error
+    );
+  }
+
+  // Handle 403 errors - Permission Denied
+  if (status === 403 || message?.includes('403') || message?.includes('Permission Denied')) {
+    if (message?.includes('Paid API Key') || message?.includes('billing')) {
+      return new AppError(
+        message || 'Billing required',
+        'BILLING_REQUIRED',
+        '此功能需要付費 API Key，請在設置中切換到免費模型或啟用付費帳戶',
+        true,
+        error
+      );
+    }
+    return new AppError(
+      message || 'Permission denied',
+      'PERMISSION_DENIED',
+      'API Key 無效或沒有權限，請檢查設置',
+      true,
+      error
+    );
+  }
+
+  // Handle 429 errors - Rate Limit
+  if (status === 429 || message?.includes('429') || message?.includes('rate limit')) {
+    return new AppError(
+      message || 'Rate limit exceeded',
+      'RATE_LIMIT',
+      '請求過於頻繁，請稍後再試',
+      true,
+      error
+    );
+  }
+
+  // Handle 500 errors - Server Error
+  if (status === 500 || status === 503 || message?.includes('overloaded')) {
+    return new AppError(
+      message || 'Server error',
+      'SERVER_ERROR',
+      '服務器暫時無法處理請求，請稍後再試',
+      true,
+      error
+    );
+  }
+
+  // Handle network errors
+  if (message?.includes('network') || message?.includes('fetch')) {
+    return new AppError(
+      message || 'Network error',
+      'NETWORK_ERROR',
+      '網路連線錯誤，請檢查網路連線',
+      true,
+      error
+    );
+  }
+
+  // Default error
+  return new AppError(
+    message || 'An unexpected error occurred',
+    'UNKNOWN_ERROR',
+    '發生未知錯誤，請稍後再試',
+    false,
+    error
+  );
+};
+
+/**
+ * Get user-friendly error message
+ */
+export const getUserFriendlyErrorMessage = (error: Error | AppError): string => {
+  if (error instanceof AppError) {
+    return error.userMessage;
+  }
+  return error.message || '發生未知錯誤';
+};

package/utils/imageUtils.ts

@@ -0,0 +1,135 @@
+import { IMAGE_CONSTANTS } from "../constants";
+
+/**
+ * Process image data URL and extract mime type and base64 data
+ * @param dataUrl - The data URL string
+ * @returns Object with mimeType and base64Data, or null if invalid
+ */
+export const processImageDataUrl = (dataUrl: string): { mimeType: string; base64Data: string } | null => {
+  const base64Match = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
+  if (base64Match) {
+    return {
+      mimeType: base64Match[1],
+      base64Data: base64Match[2]
+    };
+  }
+  return null;
+};
+
+/**
+ * Compress image file to reduce size while maintaining quality
+ * @param file - The image file to compress
+ * @param maxSizeKB - Maximum file size in KB (default: 500KB)
+ * @param maxDimension - Maximum width or height in pixels (default: 1920)
+ * @returns Promise resolving to compressed image data URL
+ */
+export const compressImage = async (
+  file: File, 
+  maxSizeKB: number = IMAGE_CONSTANTS.MAX_SIZE_KB,
+  maxDimension: number = IMAGE_CONSTANTS.MAX_DIMENSION
+): Promise<string> => {
+  return new Promise((resolve, reject) => {
+    // Validate file type
+    if (!file.type.startsWith('image/')) {
+      reject(new Error('File is not an image'));
+      return;
+    }
+
+    const reader = new FileReader();
+    reader.onload = (e) => {
+      const img = new Image();
+      img.onload = () => {
+        const canvas = document.createElement('canvas');
+        let width = img.width;
+        let height = img.height;
+        
+        // Calculate new dimensions to fit within maxDimension
+        if (width > height && width > maxDimension) {
+          height = (height * maxDimension) / width;
+          width = maxDimension;
+        } else if (height > maxDimension) {
+          width = (width * maxDimension) / height;
+          height = maxDimension;
+        }
+        
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext('2d');
+        
+        if (!ctx) {
+          reject(new Error('Could not get canvas context'));
+          return;
+        }
+        
+        // Draw image with new dimensions
+        ctx.drawImage(img, 0, 0, width, height);
+        
+        // Convert to blob with quality compression
+        canvas.toBlob(
+          (blob) => {
+            if (!blob) {
+              reject(new Error('Failed to compress image'));
+              return;
+            }
+            
+            // Check if compressed size is acceptable
+            const sizeKB = blob.size / 1024;
+            if (sizeKB <= maxSizeKB) {
+              // Size is acceptable, convert to data URL
+              const reader = new FileReader();
+              reader.onload = () => resolve(reader.result as string);
+              reader.onerror = () => reject(new Error('Failed to read compressed image'));
+              reader.readAsDataURL(blob);
+            } else {
+              // Still too large, try lower quality
+              const quality = Math.max(
+                IMAGE_CONSTANTS.MIN_COMPRESSION_QUALITY, 
+                IMAGE_CONSTANTS.COMPRESSION_QUALITY * (maxSizeKB / sizeKB)
+              );
+              canvas.toBlob(
+                (compressedBlob) => {
+                  if (!compressedBlob) {
+                    reject(new Error('Failed to compress image'));
+                    return;
+                  }
+                  const finalReader = new FileReader();
+                  finalReader.onload = () => resolve(finalReader.result as string);
+                  finalReader.onerror = () => reject(new Error('Failed to read compressed image'));
+                  finalReader.readAsDataURL(compressedBlob);
+                },
+                'image/jpeg',
+                quality
+              );
+            }
+          },
+          'image/jpeg',
+          IMAGE_CONSTANTS.COMPRESSION_QUALITY // Initial quality
+        );
+      };
+      img.onerror = () => reject(new Error('Failed to load image'));
+      img.src = e.target?.result as string;
+    };
+    reader.onerror = () => reject(new Error('Failed to read file'));
+    reader.readAsDataURL(file);
+  });
+};
+
+/**
+ * Validate image file
+ * @param file - The file to validate
+ * @param maxSizeMB - Maximum file size in MB (default: 10MB)
+ * @returns Error message if invalid, null if valid
+ */
+export const validateImageFile = (file: File, maxSizeMB: number = IMAGE_CONSTANTS.MAX_FILE_SIZE_MB): string | null => {
+  // Validate file type
+  if (!file.type.startsWith('image/')) {
+    return 'Please upload an image file (JPG, PNG, etc.)';
+  }
+
+  // Validate file size
+  if (file.size > maxSizeMB * 1024 * 1024) {
+    return `Image file is too large. Maximum size is ${maxSizeMB}MB.`;
+  }
+
+  return null;
+};

package/utils/retry.ts

@@ -0,0 +1,41 @@
+/**
+ * Retry a function with exponential backoff
+ * @param fn - The function to retry
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param initialDelay - Initial delay in milliseconds (default: 1000)
+ * @returns Promise resolving to the function result
+ */
+export const retryWithBackoff = async <T>(
+  fn: () => Promise<T>,
+  maxRetries: number = 3,
+  initialDelay: number = 1000
+): Promise<T> => {
+  let lastError: Error | unknown;
+  
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Don't retry on certain errors (4xx client errors except 429)
+      if (error && typeof error === 'object' && 'status' in error) {
+        const status = (error as { status?: number }).status;
+        if (status && status >= 400 && status < 500 && status !== 429) {
+          throw error;
+        }
+      }
+      
+      // If this is the last retry, throw the error
+      if (i === maxRetries - 1) {
+        throw error;
+      }
+      
+      // Calculate delay with exponential backoff
+      const delay = initialDelay * Math.pow(2, i);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError || new Error('Max retries exceeded');
+};