Skip to content

matutetandil/yampp-translator

BranchesTags

Repository files navigation

yampp-translator

npm version Node.js

AI-powered translator for converting build tools (Makefile, Gulpfile, npm scripts, Justfile, Gradle, CMake, Bazel) to Yamfile format. Supports 9 AI providers including local models (Ollama, Hugging Face) and cloud services (OpenAI, Claude, Gemini, and more) to provide intelligent, context-aware translations.

⚠️ Important Disclaimer

yampp-translator uses AI to generate translations. While it provides a good starting point, the generated Yamfiles should always be reviewed and tested before use in production environments. AI translations may not capture all nuances of complex build systems.

Features

  • 🔄 Multiple Input Formats: Makefile, Gulpfile, npm scripts (package.json), Justfile, Gradle, CMake, Bazel
  • 🤖 AI-Powered: Intelligent context-aware translations using 9 AI providers (local and cloud)
  • 🏠 Universal Coverage: Local models (Ollama, Hugging Face) to enterprise APIs (OpenAI, Claude, Gemini, etc.)
  • 📝 Smart Conversion: Preserves dependencies, execution order, and build logic
  • 🎛️ Interactive Mode: Review translations before saving
  • ⚙️ Configurable: Persistent configuration with multiple AI providers
  • 🚀 Easy Setup: Interactive setup wizard and global CLI installation

Installation

npm install -g @yampp/translator

Quick Start

🖥️ CLI Interface (Traditional)

  1. Setup your AI provider:

    yampp-translator setup

  2. Translate a build file:

    yampp-translator translate Makefile
yampp-translator translate gulpfile.js
yampp-translator translate package.json
yampp-translator translate justfile
yampp-translator translate build.gradle
yampp-translator translate CMakeLists.txt
yampp-translator translate BUILD

  3. Review and test the generated Yamfile before using it!

🤖 AI Editor Agents (Interactive)

We provide specialized agents for major AI-powered editors that offer interactive, conversational translation:

Claude Code Agent

  1. Copy the agent file: 
    cp agents/yampp-translation-agent.md ~/path/to/your/claude/agents/
  2. Use directly in Claude Code:
    • Paste your Makefile, Gulpfile, package.json, justfile, build.gradle, CMakeLists.txt, or BUILD file
    • Ask: "Translate this to Yamfile format"
    • Get instant, intelligent translation with explanations

Cursor AI Agent

  1. In Cursor, go to Settings (Cmd/Ctrl + ,)
  2. Navigate to Cursor Tab → General → Rules for AI
  3. Copy agents/cursor-yampp-agent.md content into "Rules for AI"
  4. Use naturally: Select build files and ask for Yamfile translation

GitHub Copilot Instructions

  1. Repository-level: Create .github/copilot-instructions.md
  2. Copy agents/copilot-yampp-instructions.md content
  3. Global setup: Use Copilot custom instructions in VS Code
  4. Use in chat: Ask Copilot to convert build files to Yamfile

JetBrains AI Assistant / Junie

  1. For AI Assistant: Add custom prompt in Settings → Tools → AI Assistant → Prompt Library
  2. For Junie: Create .junie/guidelines.md with agents/junie-yampp-guidelines.md content
  3. Use in IDE: Select build files and apply Yampp translation prompt

Universal Agent Benefits:

  • ✅ Zero setup - Works immediately in your preferred editor
  • ✅ Interactive - Conversational refinement and improvements
  • ✅ Educational - Explains translation decisions and best practices
  • ✅ Context-aware - Understands your full project context
  • ✅ Iterative - Refine translations based on your feedback
  • ✅ Editor-native - Integrates seamlessly with your workflow

Example Usage (All Agents):

User: "Translate this Makefile to Yamfile"
Agent: *Analyzes and provides complete translation with explanations*

User: "Add interactive prompts for the deploy task"  
Agent: *Enhances with __input_confirm and __input_select functions*

User: "Why did you use the 'serial' modifier?"
Agent: *Explains dependency analysis and performance considerations*

AI Providers

yampp-translator supports 9 different AI providers to cover every user preference and use case:

Quick Provider Comparison

Provider Category Best For Cost Setup
Ollama Local/Open Source Privacy, No costs Free Local setup required
Hugging Face Local/Open Source Open models variety Free tier API key
OpenAI Enterprise/Professional Industry standard quality Pay-per-use API key
Claude (Anthropic) Enterprise/Professional High quality, large context Pay-per-use API key
Google Gemini Enterprise/Professional Fast, competitive Pay-per-use API key
Cohere Enterprise/Professional Enterprise features Pay-per-use API key
Mistral AI Specialized/Regional European, GDPR compliant Pay-per-use API key
DeepSeek Specialized/Regional Code-specialized models Pay-per-use API key
Grok (X AI) Specialized/Regional Latest, modern API Pay-per-use API key

Detailed Provider Information

Local & Open Source

Ollama (Local AI)

Pros:

  • ✅ Run locally, no API costs
  • ✅ Private data stays local
  • ✅ No rate limits
  • ✅ Works offline

Cons:

  • ❌ Requires local setup
  • ❌ Uses system resources
  • ❌ Slower than cloud APIs

Setup:

  1. Install Ollama from https://ollama.ai
  2. Pull a code model: ollama pull codellama:7b
  3. Start Ollama service
  4. Configure yampp-translator: yampp-translator setup

Recommended Models:

  • codellama:7b - Good balance of speed and quality
  • codellama:13b - Better quality, slower
  • deepseek-coder:6.7b - Fast and code-focused
  • magicoder:7b - Good for code generation

Hugging Face (Open Source Hub)

Pros:

  • ✅ Access to many open source models
  • ✅ Community-driven model ecosystem
  • ✅ Variety of specialized code models
  • ✅ Free tier available

Cons:

  • ❌ Can be slower than dedicated APIs
  • ❌ Model loading times
  • ❌ Variable quality across models

Setup:

  1. Get API key from https://huggingface.co/settings/tokens
  2. Configure: yampp-translator setup
  3. Choose your model

Recommended Models:

  • codellama/CodeLlama-7b-Instruct-hf - Meta's CodeLlama
  • bigcode/starcoder2-7b - BigCode StarCoder 2
  • deepseek-ai/deepseek-coder-6.7b-instruct - DeepSeek Coder

Enterprise & Professional

OpenAI (Industry Standard)

Pros:

  • ✅ Industry-leading quality
  • ✅ Excellent code understanding
  • ✅ Fast and reliable
  • ✅ Consistent performance

Cons:

  • ❌ Costs money per usage
  • ❌ Rate limits apply
  • ❌ Data sent to third party

Setup:

  1. Get API key from https://platform.openai.com/api-keys
  2. Configure: yampp-translator setup
  3. Choose your model

Recommended Models:

  • gpt-4o-mini - Fast and cost-effective
  • gpt-4o - Latest and most capable
  • gpt-4-turbo - Good balance of speed and quality

Claude (Anthropic)

Pros:

  • ✅ High quality translations
  • ✅ Fast response times
  • ✅ Large context windows
  • ✅ Excellent code understanding

Cons:

  • ❌ Requires API key and costs money
  • ❌ Rate limits apply
  • ❌ Requires internet connection

Setup:

  1. Get API key from https://console.anthropic.com
  2. Configure: yampp-translator setup
  3. Choose your model:
    • claude-3-haiku-20240307 - Fast and cost-effective
    • claude-3-sonnet-20240229 - Balanced performance (recommended)
    • claude-3-opus-20240229 - Highest quality (most expensive)

Google Gemini

Pros:

  • ✅ Competitive with GPT-4
  • ✅ Fast response times
  • ✅ Good pricing model
  • ✅ Large context window

Cons:

  • ❌ Requires Google Cloud setup
  • ❌ Rate limits apply
  • ❌ Newer service

Setup:

  1. Get API key from https://makersuite.google.com/app/apikey
  2. Configure: yampp-translator setup
  3. Choose your model

Recommended Models:

  • gemini-1.5-flash - Fast and efficient
  • gemini-1.5-pro - Higher quality
  • gemini-pro - Stable version

Cohere (Enterprise Focus)

Pros:

  • ✅ Enterprise-focused features
  • ✅ Good structured output
  • ✅ Reliable API
  • ✅ Business-oriented support

Cons:

  • ❌ More expensive than alternatives
  • ❌ Less code-specialized
  • ❌ Limited model variety

Setup:

  1. Get API key from https://dashboard.cohere.com/api-keys
  2. Configure: yampp-translator setup

Recommended Models:

  • command-r-plus - Most capable model
  • command-r - Balanced option
  • command - Standard model

Specialized & Regional

Mistral AI (European Alternative)

Pros:

  • ✅ European company (GDPR compliant)
  • ✅ Competitive pricing
  • ✅ Good code performance
  • ✅ Privacy-focused

Cons:

  • ❌ Newer service
  • ❌ Limited model variety
  • ❌ Less established ecosystem

Setup:

  1. Get API key from https://console.mistral.ai/
  2. Configure: yampp-translator setup

Recommended Models:

  • codestral-latest - Code-specialized model
  • mistral-large-latest - Most capable
  • mistral-medium-latest - Balanced option

DeepSeek (Code Specialist)

Pros:

  • ✅ Specialized in code tasks
  • ✅ Excellent code translation
  • ✅ Competitive pricing
  • ✅ Fast responses for code

Cons:

  • ❌ Limited to code/technical tasks
  • ❌ Newer service
  • ❌ Less general knowledge

Setup:

  1. Get API key from https://platform.deepseek.com/api_keys
  2. Configure: yampp-translator setup

Recommended Models:

  • deepseek-coder - Best for code translation
  • deepseek-chat - More general purpose

Grok (X AI)

Pros:

  • ✅ Integrated with X platform
  • ✅ Modern API design
  • ✅ Growing ecosystem
  • ✅ Competitive features

Cons:

  • ❌ Very new service
  • ❌ Limited availability
  • ❌ Rate limits

Setup:

  1. Get API key from https://console.x.ai/
  2. Configure: yampp-translator setup

Recommended Models:

  • grok-beta - Main model
  • grok-vision-beta - Vision-capable model

Usage

Basic Translation

# Auto-detect input type and translate
yampp-translator translate Makefile

# Specify input type explicitly
yampp-translator translate -t makefile Makefile
yampp-translator translate -t gulpfile gulpfile.js
yampp-translator translate -t npm package.json
yampp-translator translate -t justfile justfile
yampp-translator translate -t gradle build.gradle
yampp-translator translate -t cmake CMakeLists.txt
yampp-translator translate -t bazel BUILD

# Custom output file
yampp-translator translate Makefile -o MyYamfile

Advanced Options

# Use specific AI provider and model
yampp-translator translate Makefile -p openai -m gpt-4o-mini
yampp-translator translate Makefile -p claude -m claude-3-sonnet-20240229
yampp-translator translate Makefile -p gemini -m gemini-1.5-flash
yampp-translator translate Makefile -p mistral -m codestral-latest
yampp-translator translate Makefile -p deepseek -m deepseek-coder
yampp-translator translate Makefile -p huggingface -m codellama/CodeLlama-7b-Instruct-hf

# Interactive mode (review before saving)
yampp-translator translate Makefile --interactive

# Dry run (show translation without saving)
yampp-translator translate Makefile --dry-run

# Verbose output
yampp-translator translate Makefile --verbose

Configuration Management

# Interactive setup
yampp-translator setup

# View current configuration
yampp-translator config --list

# Set configuration values
yampp-translator config --set aiProvider=claude
yampp-translator config --set claudeApiKey=your-api-key
yampp-translator config --set aiModel=claude-3-sonnet-20240229

# Get specific value
yampp-translator config --get aiProvider

# Reset to defaults
yampp-translator config --reset

Supported Formats

# List supported input formats and AI providers
yampp-translator formats

Translation Examples

Makefile → Yamfile

Input (Makefile):

CC=gcc
CFLAGS=-Wall -g

all: main.o utils.o
	$(CC) -o app main.o utils.o

main.o: main.c
	$(CC) $(CFLAGS) -c main.c

utils.o: utils.c utils.h
	$(CC) $(CFLAGS) -c utils.c

clean:
	rm -f *.o app

.PHONY: clean

Output (Yamfile):

// Generated by yampp-translator from makefile
// Please review and test before using in production

// Variables
CC=gcc
CFLAGS=-Wall -g

// Build application
all needs main.o utils.o {
    $CC -o app main.o utils.o
}

// Compile main source
main.o watches main.c {
    $CC $CFLAGS -c main.c
}

// Compile utils with header dependency
utils.o watches utils.c utils.h {
    $CC $CFLAGS -c utils.c
}

// Clean build artifacts
always: clean {
    rm -f *.o app
}

package.json → Yamfile

Input (package.json scripts):

{
  "scripts": {
    "clean": "rimraf dist/",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/",
    "dev": "webpack --mode development --watch",
    "start": "node server.js",
    "prebuild": "npm run clean && npm run lint"
  }
}

Output (Yamfile):

// Generated by yampp-translator from npm
// Please review and test before using in production

// Clean build directory
always: clean {
    rm -rf dist/
}

// Lint source code
lint {
    eslint src/
}

// Build for production
build needs clean lint {
    webpack --mode production
}

// Run tests
critical: test {
    jest
}

// Development server with watching
dev watches src/**/*.js {
    webpack --mode development --watch
}

// Start production server
start needs build {
    node server.js
}

Advanced Features Support

yampp-translator now supports all advanced Yamfile features including internal functions for user interaction:

Interactive Internal Functions

// Get user input
setup {
    __input "Enter project name:" project_name "MyProject"
    __input_password "Enter database password:" db_pass
    __input_select "Choose environment:" env ["development", "staging", "production"] "development"
    __input_confirm "Deploy to production?" confirm false
    
    echo "Project: $project_name"
    echo "Environment: $env"
    if [ "$confirm" = "true" ]; then
        echo "Deploying to production..."
    fi
}

// Task composition with __call
deploy needs setup {
    __call validate
    __call build  
    __call test
    echo "Deployment complete!"
}

validate {
    echo "Validating configuration..."
}

Available Internal Functions:

  • __input "prompt" variable "default" - Get user text input
  • __input_password "prompt" variable "default" - Get secure password input
  • __input_select "prompt" variable ["opt1", "opt2"] "default" - Multiple choice selection
  • __input_confirm "prompt" variable true/false - Yes/No confirmation
  • __call taskname - Call and execute another task

These functions enable interactive builds and complex task composition, perfect for deployment scripts, setup wizards, and configuration tasks.

Configuration File

Configuration is stored in ~/.yampp-translator/config.json:

{
  "aiProvider": "ollama",
  "aiModel": "codellama:7b",
  "ollamaUrl": "http://localhost:11434",
  "claudeApiKey": null,
  "verbose": false,
  "interactive": true,
  "timeout": 120000
}

Environment Variables

You can also use environment variables:

  • CLAUDE_API_KEY - Claude API key
  • OLLAMA_URL - Ollama server URL
  • YAMPP_TRANSLATOR_VERBOSE - Enable verbose output

API Reference

CLI Commands

Command Description
translate <input> Translate build file to Yamfile
config Manage configuration
setup Interactive setup wizard
formats List supported formats

Translation Options

Option Description Default
-o, --output <file> Output file path Yamfile
-t, --type <type> Input type (auto, makefile, gulpfile, npm, justfile, gradle, cmake, bazel) auto
-p, --provider <provider> AI provider (ollama, claude) From config
-m, --model <model> AI model to use From config
-d, --dry-run Show translation without writing false
-v, --verbose Verbose output From config
-i, --interactive Interactive review mode From config

Troubleshooting

Common Issues

"Cannot connect to Ollama"

  • Ensure Ollama is installed and running
  • Check the URL: ollama list should work
  • Verify firewall/network settings

"Model not found"

  • Pull the model: ollama pull codellama:7b
  • Check available models: ollama list
  • Use a different model in config

"Invalid Claude API key"

  • Verify your API key at https://console.anthropic.com
  • Check the key is set: yampp-translator config --get claudeApiKey
  • Ensure you have API credits

"Translation quality is poor"

  • Try a different/larger model
  • Use Claude for better quality (costs money)
  • Review and manually adjust the output
  • Simplify complex build scripts before translation

Debug Mode

Enable verbose output to see detailed translation process:

yampp-translator translate Makefile --verbose

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

  • yampp - The Yamfile task runner
  • Ollama - Local AI model runtime
  • Claude - Anthropic's AI assistant

Changelog

See CHANGELOG.md for version history and changes.

⚠️ Remember: Always review and test AI-generated translations before using them in production!

About

AI-powered translator for converting build tools (Makefile, Gulpfile, npm scripts) to [Yamfile](https://github.com/matiasdenda/yampp) format. Uses local AI models via Ollama or cloud AI via Claude to provide intelligent, context-aware translations.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages