fix: Make translate_only.py and convert_to_html.py work as CLI tools from any directory

lufftw · lufftw · commit 98491b99229b · 2025-12-15T13:45:22.000+08:00
- Resolve relative paths relative to script directory (Path(__file__).parent)
- Support absolute paths directly
- Add validation to prevent empty output files
- Add detailed error messages and debugging info
- Maintain compatibility with main.py when run from script directory
diff --git a/docs/pages/mindmaps/neetcode_ontology_agent_evolved_zh-TW.html b/docs/pages/mindmaps/neetcode_ontology_agent_evolved_zh-TW.html
@@ -3,7 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>NeetCode Agent Evolved Mindmap (繁體中文) - NeetCode Mind Maps</title>
+    <title>NeetCode Agent Evolved Mindmap (ZH-TW) - NeetCode Mind Maps</title>
     <style>
         * { margin: 0; padding: 0; box-sizing: border-box; }
         html, body { height: 100%; }
diff --git a/tools/ai-markmap-agent/README.md b/tools/ai-markmap-agent/README.md
@@ -243,50 +243,73 @@ The output will be saved to:
 
 If you want to translate a specific English file:
 
-**Important**: Run the command from the `tools/ai-markmap-agent/` directory, or use absolute paths.
+**Important**: 
+- **Default output location**: When using `--output`, files are saved to the specified path
+- **Auto-detection**: Without `--output`, files are saved to `docs/mindmaps/` (configured in `config.yaml`)
+- **Version history**: The main pipeline also saves to `outputs/versions/v1/` for tracking, but `translate_only.py` only saves to the final location
+
+**Working with `docs/mindmaps/` directory:**
 
 **Unix/macOS:**
 ```bash
 # Navigate to the script directory first
 cd tools/ai-markmap-agent
 
-# Translate a specific file (auto-detects output path)
+# Translate a specific file (auto-detects output to docs/mindmaps/)
 python translate_only.py --input ../../docs/mindmaps/neetcode_ontology_agent_evolved_en.md
 
-# Or with explicit output path
+# Or with explicit output path to docs/mindmaps/
 python translate_only.py \
     --input ../../docs/mindmaps/neetcode_ontology_agent_evolved_en.md \
     --output ../../docs/mindmaps/neetcode_ontology_agent_evolved_zh-TW.md
+
+# Translate and generate HTML in one step
+python translate_only.py \
+    --input ../../docs/mindmaps/neetcode_ontology_agent_evolved_en.md \
+    --output ../../docs/mindmaps/neetcode_ontology_agent_evolved_zh-TW.md \
+    --html
 ```
 
 **Windows PowerShell:**
 ```powershell
 # Navigate to the script directory first
 cd tools\ai-markmap-agent
 
-# Translate a specific file (auto-detects output path)
+# Translate a specific file (auto-detects output to docs\mindmaps\)
 python translate_only.py --input ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_en.md
 
-# Or with explicit output path
+# Or with explicit output path to docs\mindmaps\
 python translate_only.py `
     --input ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_en.md `
     --output ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_zh-TW.md
+
+# Translate and generate HTML in one step
+python translate_only.py `
+    --input ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_en.md `
+    --output ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_zh-TW.md `
+    --html
 ```
 
-**Alternative: Use absolute paths from any directory:**
+**From Project Root (Alternative):**
 ```bash
-# Unix/macOS
+# Unix/macOS - from project root
 python tools/ai-markmap-agent/translate_only.py \
     --input docs/mindmaps/neetcode_ontology_agent_evolved_en.md \
     --output docs/mindmaps/neetcode_ontology_agent_evolved_zh-TW.md
 ```
 
 ```powershell
-# Windows PowerShell
+# Windows PowerShell - from project root
 python tools\ai-markmap-agent\translate_only.py `
     --input docs\mindmaps\neetcode_ontology_agent_evolved_en.md `
     --output docs\mindmaps\neetcode_ontology_agent_evolved_zh-TW.md
 ```
+
+**Note on Output Locations:**
+- **Version History** (main pipeline only): `tools/ai-markmap-agent/outputs/versions/v1/` (for tracking changes)
+- **Final Output** (translate_only.py): `docs/mindmaps/` (for actual use)
+- When using `--output`, the file is saved to the specified path
+- When not using `--output`, it auto-detects based on config (saves to `docs/mindmaps/`)
 **Method 3: Translate and Generate HTML in One Step**
 
 ```bash
@@ -326,8 +349,15 @@ python translate_only.py --model gpt-4o
 
 For converting Markdown files to HTML without running the full pipeline:
 
+**Important**: Run from `tools/ai-markmap-agent/` directory, or use absolute paths.
+
+**Basic Usage:**
+
 ```bash
-# Basic conversion (output: input.html)
+# Navigate to script directory
+cd tools/ai-markmap-agent
+
+# Basic conversion (output: input.html in same directory)
 python convert_to_html.py input.md
 
 # Specify output file
@@ -340,6 +370,50 @@ python convert_to_html.py input.md -t "My Mind Map"
 python convert_to_html.py input.md --template templates/custom.html
 ```
 
+**Working with `docs/mindmaps/` directory:**
+
+```bash
+# From tools/ai-markmap-agent/ directory
+# Convert English version
+python convert_to_html.py \
+    ../../docs/mindmaps/neetcode_ontology_agent_evolved_en.md \
+    -o ../../docs/pages/mindmaps/neetcode_ontology_agent_evolved_en.html \
+    -t "NeetCode Agent Evolved Mindmap (EN)"
+
+# Convert Traditional Chinese version
+python convert_to_html.py \
+    ../../docs/mindmaps/neetcode_ontology_agent_evolved_zh-TW.md \
+    -o ../../docs/pages/mindmaps/neetcode_ontology_agent_evolved_zh-TW.html \
+    -t "NeetCode Agent Evolved Mindmap (繁體中文)"
+```
+
+**Windows PowerShell:**
+
+```powershell
+# From tools\ai-markmap-agent\ directory
+# Convert English version
+python convert_to_html.py `
+    ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_en.md `
+    -o ..\..\docs\pages\mindmaps\neetcode_ontology_agent_evolved_en.html `
+    -t "NeetCode Agent Evolved Mindmap (EN)"
+
+# Convert Traditional Chinese version
+python convert_to_html.py `
+    ..\..\docs\mindmaps\neetcode_ontology_agent_evolved_zh-TW.md `
+    -o ..\..\docs\pages\mindmaps\neetcode_ontology_agent_evolved_zh-TW.html `
+    -t "NeetCode Agent Evolved Mindmap (繁體中文)"
+```
+
+**From Project Root (Alternative):**
+
+```bash
+# From project root directory
+python tools/ai-markmap-agent/convert_to_html.py \
+    docs/mindmaps/neetcode_ontology_agent_evolved_en.md \
+    -o docs/pages/mindmaps/neetcode_ontology_agent_evolved_en.html \
+    -t "NeetCode Agent Evolved Mindmap (EN)"
+```
+
 This tool is **completely independent** of the main pipeline and only requires:
 - Python 3.10+
 - `jinja2` package
diff --git a/tools/ai-markmap-agent/convert_to_html.py b/tools/ai-markmap-agent/convert_to_html.py
@@ -98,7 +98,7 @@ def convert_file_to_html(
     Convert a Markdown file to HTML (programmatic interface).
     
     Args:
-        input_path: Path to input Markdown file
+        input_path: Path to input Markdown file (can be relative or absolute)
         output_path: Path to output HTML file (default: same as input with .html)
         title: Optional HTML page title
         template_path: Optional custom template path
@@ -108,14 +108,26 @@ def convert_file_to_html(
         
     This function can be imported and used programmatically.
     """
-    input_path = Path(input_path).resolve()
+    # Resolve input path (handles both absolute and relative paths)
+    input_path = Path(input_path)
+    if not input_path.is_absolute():
+        # If relative, resolve relative to current working directory
+        # (This is correct for programmatic calls where paths are already resolved)
+        input_path = input_path.resolve()
+    else:
+        input_path = input_path.resolve()
+    
     if not input_path.exists():
         raise FileNotFoundError(f"Input file not found: {input_path}")
     
     if output_path is None:
         output_path = input_path.with_suffix(".html")
     else:
-        output_path = Path(output_path).resolve()
+        output_path = Path(output_path)
+        if not output_path.is_absolute():
+            output_path = output_path.resolve()
+        else:
+            output_path = output_path.resolve()
     
     output_path.parent.mkdir(parents=True, exist_ok=True)
     
@@ -183,10 +195,21 @@ def main() -> int:
     args = parser.parse_args()
     
     try:
+        # Get script base directory for resolving relative paths (CLI tool behavior)
+        script_base_dir = Path(__file__).parent
+        
         # Resolve input path
-        input_path = Path(args.input).resolve()
+        # Relative paths are resolved relative to script directory, not current working directory
+        input_path = Path(args.input)
+        if not input_path.is_absolute():
+            input_path = (script_base_dir / input_path).resolve()
+        else:
+            input_path = input_path.resolve()
+        
         if not input_path.exists():
             print(f"❌ Error: Input file not found: {input_path}")
+            print(f"   Resolved from: {args.input}")
+            print(f"   Script directory: {script_base_dir}")
             return 1
         
         if not input_path.is_file():
@@ -195,7 +218,12 @@ def main() -> int:
         
         # Determine output path
         if args.output:
-            output_path = Path(args.output).resolve()
+            output_path = Path(args.output)
+            # Resolve relative paths relative to script directory (CLI tool behavior)
+            if not output_path.is_absolute():
+                output_path = (script_base_dir / output_path).resolve()
+            else:
+                output_path = output_path.resolve()
         else:
             output_path = input_path.with_suffix(".html")
         
diff --git a/tools/ai-markmap-agent/translate_only.py b/tools/ai-markmap-agent/translate_only.py
@@ -95,14 +95,34 @@ def translate_file(
     print("\n⏳ Translating...")
     translated = translator.translate(content, "general")
     
+    # Validate translation result
+    if not translated:
+        raise ValueError("Translation returned empty content. Check API key and model configuration.")
+    if len(translated.strip()) == 0:
+        raise ValueError("Translation returned only whitespace. Check API response.")
+    
+    print(f"   Raw translation: {len(translated)} chars")
+    
     # Clean up LLM artifacts
     translated = clean_translated_content(translated)
-    print(f"   ✓ Translated to {len(translated)} chars")
+    
+    # Validate cleaned content
+    if not translated or len(translated.strip()) == 0:
+        raise ValueError("After cleaning, translation is empty. Check clean_translated_content function.")
+    
+    print(f"   ✓ Cleaned translation: {len(translated)} chars, {len(translated.splitlines())} lines")
     
     # Save output
     output_path.parent.mkdir(parents=True, exist_ok=True)
     output_path.write_text(translated, encoding="utf-8")
-    print(f"\n💾 Saved: {output_path}")
+    
+    # Verify file was written
+    if not output_path.exists():
+        raise IOError(f"Failed to write output file: {output_path}")
+    if output_path.stat().st_size == 0:
+        raise IOError(f"Output file is empty: {output_path}")
+    
+    print(f"\n💾 Saved: {output_path} ({output_path.stat().st_size} bytes)")
     
     return translated
 
@@ -170,11 +190,21 @@ def main() -> int:
             print("\n❌ Error: OpenAI API key is required.")
             return 1
         
+        # Get script base directory for resolving relative paths
+        script_base_dir = Path(__file__).parent
+        
         # Determine input file
         if args.input:
             input_path = Path(args.input)
+            # Resolve relative paths relative to script directory (CLI tool behavior)
+            if not input_path.is_absolute():
+                input_path = (script_base_dir / input_path).resolve()
+            else:
+                input_path = input_path.resolve()
+            
             if not input_path.exists():
                 print(f"\n❌ Error: Input file not found: {args.input}")
+                print(f"   Resolved path: {input_path}")
                 return 1
         else:
             input_path = find_latest_english_output(config)
@@ -190,6 +220,11 @@ def main() -> int:
         # Determine output file
         if args.output:
             output_path = Path(args.output)
+            # Resolve relative paths relative to script directory (CLI tool behavior)
+            if not output_path.is_absolute():
+                output_path = (script_base_dir / output_path).resolve()
+            else:
+                output_path = output_path.resolve()
         else:
             # Replace language suffix in filename (only at the end!)
             stem = input_path.stem
@@ -231,8 +266,7 @@ def main() -> int:
             
             # Get HTML output directory from config
             final_dirs = config.get("output", {}).get("final_dirs", {})
-            base_dir = Path(__file__).parent
-            html_output_dir = (base_dir / final_dirs.get("html", "outputs/final")).resolve()
+            html_output_dir = (script_base_dir / final_dirs.get("html", "outputs/final")).resolve()
             html_output_dir.mkdir(parents=True, exist_ok=True)
             
             html_path = html_output_dir / f"{output_path.stem}.html"
