melaka 0.0.0

package/packages/ai/src/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Melaka AI - Provider Interface
+ *
+ * Defines the common interface all AI providers must implement.
+ */
+
+import type { z } from 'zod';
+
+/**
+ * Configuration for an AI translation request.
+ */
+export interface TranslationOptions {
+  /**
+   * Target language code (BCP 47 format).
+   * @example 'ms-MY', 'zh-CN'
+   */
+  targetLanguage: string;
+
+  /**
+   * Custom prompt/context for the translation.
+   */
+  prompt?: string;
+
+  /**
+   * Glossary of terms to preserve or translate consistently.
+   */
+  glossary?: Record<string, string>;
+
+  /**
+   * Temperature for generation (0-1).
+   */
+  temperature?: number;
+}
+
+/**
+ * Result of an AI translation.
+ */
+export interface TranslationResponse<T = Record<string, unknown>> {
+  /**
+   * Whether the translation succeeded.
+   */
+  success: boolean;
+
+  /**
+   * Translated content (matches input schema structure).
+   */
+  output?: T;
+
+  /**
+   * Error message if failed.
+   */
+  error?: string;
+
+  /**
+   * Token usage statistics.
+   */
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+  };
+
+  /**
+   * Duration in milliseconds.
+   */
+  durationMs?: number;
+}
+
+/**
+ * Common interface for all AI providers.
+ *
+ * Each provider (Gemini, OpenAI, Claude) implements this interface.
+ */
+export interface AIProvider {
+  /**
+   * Provider name for identification.
+   */
+  readonly name: string;
+
+  /**
+   * Translate content using the AI provider.
+   *
+   * @param content - Content to translate (translatable fields only)
+   * @param schema - Zod schema defining the expected output structure
+   * @param options - Translation options (language, prompt, glossary)
+   * @returns Translation result
+   *
+   * @example
+   * ```typescript
+   * const result = await provider.translate(
+   *   { title: 'Hello World', body: 'Welcome to our app' },
+   *   z.object({ title: z.string(), body: z.string() }),
+   *   { targetLanguage: 'ms-MY' }
+   * );
+   * ```
+   */
+  translate<T>(
+    content: Record<string, unknown>,
+    schema: z.ZodSchema<T>,
+    options: TranslationOptions
+  ): Promise<TranslationResponse<T>>;
+
+  /**
+   * Check if the provider is properly configured.
+   *
+   * @returns Whether the provider has valid credentials
+   */
+  isConfigured(): boolean;
+
+  /**
+   * Get the model name being used.
+   */
+  getModel(): string;
+}
+
+/**
+ * Configuration for creating an AI provider instance.
+ */
+export interface ProviderConfig {
+  /**
+   * API key for the provider.
+   */
+  apiKey?: string;
+
+  /**
+   * Model name to use.
+   */
+  model: string;
+
+  /**
+   * Default temperature for generation.
+   */
+  temperature?: number;
+}

package/packages/ai/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/cli/README.md

@@ -0,0 +1,70 @@
+# @melaka/cli
+
+Command-line interface for Melaka - AI-powered Firestore localization.
+
+## Installation
+
+```bash
+npm install -g @melaka/cli
+# or
+pnpm add -g @melaka/cli
+```
+
+## Commands
+
+### `melaka init`
+
+Initialize Melaka in your Firebase project.
+
+```bash
+cd your-firebase-project
+melaka init
+```
+
+Creates `melaka.config.ts` with a starter configuration.
+
+### `melaka deploy`
+
+Generate and deploy Melaka Cloud Functions.
+
+```bash
+melaka deploy
+```
+
+Options:
+- `-o, --output <dir>` — Output directory (default: `functions/src/melaka`)
+- `--no-firebase` — Generate only, skip deployment
+- `--dry-run` — Show what would be generated
+
+### `melaka translate`
+
+Manually trigger translation for collections.
+
+```bash
+melaka translate
+melaka translate --collection products
+melaka translate --collection products --language ms-MY
+melaka translate --force
+```
+
+### `melaka status`
+
+Check translation status and configuration.
+
+```bash
+melaka status
+melaka status --collection products
+melaka status --json
+```
+
+### `melaka validate`
+
+Validate your `melaka.config.ts`.
+
+```bash
+melaka validate
+```
+
+## Documentation
+
+See the [main Melaka documentation](https://github.com/rizahassan/melaka).

package/packages/cli/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@melaka/cli",
+  "version": "0.0.0",
+  "description": "CLI for Melaka - AI-powered Firestore localization",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "melaka": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts --format cjs --dts",
+    "dev": "tsup src/cli.ts --format cjs --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@melaka/core": "workspace:*",
+    "@melaka/firestore": "workspace:*",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0",
+    "@types/node": "^20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rizahassan/melaka.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/cli/src/cli.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Melaka CLI
+ *
+ * Command-line interface for Melaka - AI-powered Firestore localization.
+ */
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init';
+import { deployCommand } from './commands/deploy';
+import { translateCommand } from './commands/translate';
+import { statusCommand } from './commands/status';
+import { validateCommand } from './commands/validate';
+
+const program = new Command();
+
+program
+  .name('melaka')
+  .description('AI-powered localization for Firebase Firestore')
+  .version('0.0.0');
+
+// Register commands
+program.addCommand(initCommand);
+program.addCommand(deployCommand);
+program.addCommand(translateCommand);
+program.addCommand(statusCommand);
+program.addCommand(validateCommand);
+
+// Parse arguments
+program.parse();

package/packages/cli/src/commands/deploy.ts

@@ -0,0 +1,115 @@
+/**
+ * Melaka CLI - Deploy Command
+ *
+ * Generate and deploy Melaka Cloud Functions.
+ */
+
+import { Command } from 'commander';
+import { writeFile, mkdir, access } from 'fs/promises';
+import { join, dirname } from 'path';
+import { loadConfig } from '@melaka/core';
+import { generateTriggers, type GeneratedFile } from '@melaka/firestore';
+
+export const deployCommand = new Command('deploy')
+  .description('Generate and deploy Melaka triggers')
+  .option('-o, --output <dir>', 'Output directory for generated files', 'functions/src/melaka')
+  .option('--no-firebase', 'Skip Firebase deployment (generate only)')
+  .option('--dry-run', 'Show what would be generated without writing')
+  .action(async (options) => {
+    const chalk = (await import('chalk')).default;
+    const ora = (await import('ora')).default;
+
+    // Load config
+    const configSpinner = ora('Loading melaka.config.ts...').start();
+    let config;
+
+    try {
+      config = await loadConfig();
+      configSpinner.succeed(`Loaded config: ${config.collections.length} collections, ${config.languages.length} languages`);
+    } catch (error) {
+      configSpinner.fail('Failed to load config');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+
+    // Generate files
+    const genSpinner = ora('Generating Cloud Functions...').start();
+
+    try {
+      const files = generateTriggers(config, {
+        outputDir: options.output,
+      });
+
+      if (options.dryRun) {
+        genSpinner.succeed('Generated (dry run)');
+        console.log('');
+        console.log(chalk.gray('Files that would be created:'));
+        for (const file of files) {
+          console.log(chalk.cyan(`  ${options.output}/${file.path}`));
+        }
+        console.log('');
+        return;
+      }
+
+      // Write files
+      await writeGeneratedFiles(files, options.output);
+      genSpinner.succeed(`Generated ${files.length} files in ${options.output}/`);
+    } catch (error) {
+      genSpinner.fail('Failed to generate files');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+
+    // Deploy to Firebase (unless --no-firebase)
+    if (options.firebase !== false) {
+      console.log('');
+      console.log(chalk.yellow('📦 To deploy to Firebase, run:'));
+      console.log(chalk.cyan('   firebase deploy --only functions'));
+      console.log('');
+      console.log(chalk.gray('Or add the exports to your functions/src/index.ts:'));
+      console.log(chalk.gray(`   export * from './melaka';`));
+    }
+
+    // Show summary
+    console.log('');
+    console.log(chalk.green('✨ Melaka triggers generated!'));
+    console.log('');
+    console.log('Generated triggers:');
+    for (const collection of config.collections) {
+      const name = `melakaTranslate${pascalCase(collection.path)}`;
+      console.log(chalk.gray(`  - ${name} → ${collection.path}`));
+    }
+    console.log(chalk.gray('  - melakaTranslateTask (task handler)'));
+    console.log('');
+  });
+
+/**
+ * Write generated files to disk.
+ */
+async function writeGeneratedFiles(
+  files: GeneratedFile[],
+  outputDir: string
+): Promise<void> {
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+
+  for (const file of files) {
+    const filePath = join(outputDir, file.path);
+    const fileDir = dirname(filePath);
+
+    // Ensure parent directory exists
+    await mkdir(fileDir, { recursive: true });
+
+    await writeFile(filePath, file.content);
+  }
+}
+
+/**
+ * Convert string to PascalCase.
+ */
+function pascalCase(str: string): string {
+  return str
+    .split(/[-_\/]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}

package/packages/cli/src/commands/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Melaka CLI - Command Exports
+ */
+
+export { initCommand } from './init';
+export { deployCommand } from './deploy';
+export { translateCommand } from './translate';
+export { statusCommand } from './status';
+export { validateCommand } from './validate';

package/packages/cli/src/commands/init.ts

@@ -0,0 +1,107 @@
+/**
+ * Melaka CLI - Init Command
+ *
+ * Initialize a new melaka.config.ts in the current project.
+ */
+
+import { Command } from 'commander';
+import { writeFile, access } from 'fs/promises';
+import { join } from 'path';
+
+export const initCommand = new Command('init')
+  .description('Initialize Melaka in your Firebase project')
+  .option('-f, --force', 'Overwrite existing config file')
+  .action(async (options) => {
+    const chalk = (await import('chalk')).default;
+    const ora = (await import('ora')).default;
+
+    const configPath = join(process.cwd(), 'melaka.config.ts');
+
+    // Check if config already exists
+    try {
+      await access(configPath);
+      if (!options.force) {
+        console.log(chalk.yellow('⚠️  melaka.config.ts already exists.'));
+        console.log(chalk.gray('   Use --force to overwrite.'));
+        return;
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+
+    const spinner = ora('Creating melaka.config.ts...').start();
+
+    try {
+      await writeFile(configPath, CONFIG_TEMPLATE);
+      spinner.succeed('Created melaka.config.ts');
+
+      console.log('');
+      console.log(chalk.green('✨ Melaka initialized!'));
+      console.log('');
+      console.log('Next steps:');
+      console.log(chalk.gray('  1. Edit melaka.config.ts with your collections'));
+      console.log(chalk.gray('  2. Set up your AI API key:'));
+      console.log(chalk.cyan('     firebase functions:secrets:set GEMINI_API_KEY'));
+      console.log(chalk.gray('  3. Deploy triggers:'));
+      console.log(chalk.cyan('     melaka deploy'));
+      console.log('');
+    } catch (error) {
+      spinner.fail('Failed to create config file');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+  });
+
+const CONFIG_TEMPLATE = `import { defineConfig } from 'melaka';
+
+/**
+ * Melaka Configuration
+ * 
+ * Configure your Firestore collections for automatic AI translation.
+ * 
+ * @see https://github.com/rizahassan/melaka/blob/main/docs/CONFIGURATION.md
+ */
+export default defineConfig({
+  // Target languages (BCP 47 format)
+  languages: ['ms-MY', 'zh-CN'],
+
+  // AI provider configuration
+  ai: {
+    provider: 'gemini',
+    model: 'gemini-2.5-flash',
+    apiKeySecret: 'GEMINI_API_KEY', // Firebase secret name
+    temperature: 0.3,
+  },
+
+  // Firebase region (should match your Firestore region)
+  region: 'us-central1',
+
+  // Default settings for all collections
+  defaults: {
+    batchSize: 20,
+    maxConcurrency: 10,
+    forceUpdate: false,
+  },
+
+  // Shared glossary (optional)
+  // Terms here are used consistently across all collections
+  glossary: {
+    // 'brand_name': 'Brand Name', // Don't translate
+  },
+
+  // Collections to translate
+  collections: [
+    {
+      path: 'articles',
+      fields: ['title', 'content', 'summary'],
+      prompt: 'Blog article content. Maintain markdown formatting.',
+    },
+    // Add more collections as needed:
+    // {
+    //   path: 'products',
+    //   fields: ['name', 'description'],
+    //   prompt: 'E-commerce product descriptions.',
+    // },
+  ],
+});
+`;

package/packages/cli/src/commands/status.ts

@@ -0,0 +1,73 @@
+/**
+ * Melaka CLI - Status Command
+ *
+ * Check translation status for collections.
+ */
+
+import { Command } from 'commander';
+import { loadConfig, getLanguageName } from '@melaka/core';
+
+export const statusCommand = new Command('status')
+  .description('Check translation status')
+  .option('-c, --collection <path>', 'Specific collection to check')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const chalk = (await import('chalk')).default;
+    const ora = (await import('ora')).default;
+
+    // Load config
+    const configSpinner = ora('Loading melaka.config.ts...').start();
+    let config;
+
+    try {
+      config = await loadConfig();
+      configSpinner.succeed('Loaded config');
+    } catch (error) {
+      configSpinner.fail('Failed to load config');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+
+    // Note: Actual status checking requires Firebase Admin SDK
+    // This is a placeholder showing the config
+    console.log('');
+    console.log(chalk.cyan('Melaka Configuration:'));
+    console.log('');
+
+    console.log(chalk.white('AI Provider:'));
+    console.log(chalk.gray(`  Provider: ${config.ai.provider}`));
+    console.log(chalk.gray(`  Model: ${config.ai.model}`));
+    console.log(chalk.gray(`  Region: ${config.region || 'us-central1'}`));
+    console.log('');
+
+    console.log(chalk.white('Languages:'));
+    for (const lang of config.languages) {
+      console.log(chalk.gray(`  - ${lang} (${getLanguageName(lang)})`));
+    }
+    console.log('');
+
+    console.log(chalk.white('Collections:'));
+    for (const collection of config.collections) {
+      const fields = collection.fields?.join(', ') || 'auto-detect';
+      console.log(chalk.gray(`  ${collection.path}`));
+      console.log(chalk.gray(`    Fields: ${fields}`));
+      if (collection.prompt) {
+        const shortPrompt = collection.prompt.length > 50 
+          ? collection.prompt.substring(0, 50) + '...'
+          : collection.prompt;
+        console.log(chalk.gray(`    Prompt: ${shortPrompt}`));
+      }
+    }
+    console.log('');
+
+    if (config.glossary && Object.keys(config.glossary).length > 0) {
+      console.log(chalk.white('Shared Glossary:'));
+      for (const [term, translation] of Object.entries(config.glossary)) {
+        console.log(chalk.gray(`  ${term} → ${translation}`));
+      }
+      console.log('');
+    }
+
+    console.log(chalk.yellow('⚠️  Live status checking requires Firebase connection.'));
+    console.log(chalk.gray('   Status will show actual translation progress in Phase 2.'));
+  });

package/packages/cli/src/commands/translate.ts

@@ -0,0 +1,92 @@
+/**
+ * Melaka CLI - Translate Command
+ *
+ * Manually trigger translation for collections.
+ */
+
+import { Command } from 'commander';
+import { loadConfig, findCollectionConfig } from '@melaka/core';
+
+export const translateCommand = new Command('translate')
+  .description('Manually translate a collection')
+  .option('-c, --collection <path>', 'Collection path to translate')
+  .option('-l, --language <code>', 'Specific language to translate')
+  .option('--force', 'Force re-translation of all documents')
+  .option('--dry-run', 'Show what would be translated without doing it')
+  .action(async (options) => {
+    const chalk = (await import('chalk')).default;
+    const ora = (await import('ora')).default;
+
+    // Load config
+    const configSpinner = ora('Loading melaka.config.ts...').start();
+    let config;
+
+    try {
+      config = await loadConfig();
+      configSpinner.succeed('Loaded config');
+    } catch (error) {
+      configSpinner.fail('Failed to load config');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+
+    // Determine which collections to translate
+    let collectionsToTranslate = config.collections;
+
+    if (options.collection) {
+      const collectionConfig = findCollectionConfig(config, options.collection);
+      if (!collectionConfig) {
+        console.error(chalk.red(`Collection not found in config: ${options.collection}`));
+        console.log(chalk.gray('Available collections:'));
+        for (const c of config.collections) {
+          console.log(chalk.gray(`  - ${c.path}`));
+        }
+        process.exit(1);
+      }
+      collectionsToTranslate = [collectionConfig];
+    }
+
+    // Determine which languages to translate
+    let languagesToTranslate = config.languages;
+
+    if (options.language) {
+      if (!config.languages.includes(options.language)) {
+        console.error(chalk.red(`Language not found in config: ${options.language}`));
+        console.log(chalk.gray('Available languages:'));
+        for (const l of config.languages) {
+          console.log(chalk.gray(`  - ${l}`));
+        }
+        process.exit(1);
+      }
+      languagesToTranslate = [options.language];
+    }
+
+    // Show what will be translated
+    console.log('');
+    console.log(chalk.cyan('Translation Plan:'));
+    console.log(chalk.gray(`  Collections: ${collectionsToTranslate.map((c) => c.path).join(', ')}`));
+    console.log(chalk.gray(`  Languages: ${languagesToTranslate.join(', ')}`));
+    console.log(chalk.gray(`  Force: ${options.force ? 'yes' : 'no'}`));
+    console.log('');
+
+    if (options.dryRun) {
+      console.log(chalk.yellow('Dry run - no translations will be performed.'));
+      console.log('');
+      console.log(chalk.gray('To perform translations, this command needs to be run'));
+      console.log(chalk.gray('in a Firebase Functions environment or with emulators.'));
+      console.log('');
+      console.log(chalk.gray('For now, use triggers or the Firebase console to trigger translations.'));
+      return;
+    }
+
+    // Note: Actual translation requires Firebase Admin SDK
+    // This is a placeholder for the MVP
+    console.log(chalk.yellow('⚠️  Manual translation requires Firebase Functions environment.'));
+    console.log('');
+    console.log('To translate documents:');
+    console.log(chalk.gray('  1. Deploy triggers: melaka deploy'));
+    console.log(chalk.gray('  2. Update a document to trigger translation'));
+    console.log(chalk.gray('  3. Or use Firebase Console to call the Cloud Task directly'));
+    console.log('');
+    console.log(chalk.gray('Batch translation via CLI will be available in Phase 2.'));
+  });