Add setup wizard, GUI launcher, and always-visible code buttons

- Show code action buttons immediately in interactive mode instead of
  gating on AI analysis completion
- Add GET /api/source/{node_id} endpoint to fetch source without
  triggering AI analysis
- Add interactive setup wizard when running codedocent with no args
  (folder picker, Ollama detection, model selection, mode choice)
- Add tkinter GUI launcher via --gui flag and codedocent-gui entry point
- Extract shared Ollama utilities to codedocent/ollama_utils.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: clanker-lover

codedocent/cli.py

@@ -3,11 +3,18 @@
 from __future__ import annotations
 
 import argparse
+import os
 
+from codedocent.ollama_utils import check_ollama, fetch_ollama_models
 from codedocent.parser import CodeNode, parse_directory
 from codedocent.scanner import scan_directory
 
 
+# Re-export for backwards compatibility and testability
+_check_ollama = check_ollama
+_fetch_ollama_models = fetch_ollama_models
+
+
 def print_tree(node: CodeNode, indent: int = 0) -> None:
     """Print a text representation of the code tree."""
     prefix = "  " * indent
@@ -34,13 +41,103 @@ def print_tree(node: CodeNode, indent: int = 0) -> None:
         print_tree(child, indent + 1)
 
 
+def _ask_folder() -> str:
+    """Prompt for a valid folder path, re-asking on invalid input."""
+    while True:
+        path = input("What folder do you want to analyze? ").strip()
+        path = os.path.expanduser(path)
+        if os.path.isdir(path):
+            file_count = len(list(scan_directory(path)))
+            print(f"\u2713 Found {file_count} files\n")
+            return path
+        print(f"  '{path}' is not a valid directory. Try again.\n")
+
+
+def _ask_no_ai_fallback() -> bool:
+    """Ask user whether to continue without AI. Returns True for no-ai."""
+    fallback = input("Continue without AI? [Y/n]: ").strip().lower()
+    if fallback in ("", "y", "yes"):
+        return True
+    raise SystemExit(0)
+
+
+def _pick_model(models: list[str]) -> str:
+    """Let the user pick from a numbered list of models."""
+    print("Available models:")
+    for i, m in enumerate(models, 1):
+        print(f"  {i}. {m}")
+    choice = input("Which model? [1]: ").strip()
+    if choice == "":
+        return models[0]
+    try:
+        idx = int(choice) - 1
+        if 0 <= idx < len(models):
+            return models[idx]
+    except ValueError:
+        pass
+    return models[0]
+
+
+def _run_wizard() -> argparse.Namespace:  # pylint: disable=too-many-branches
+    """Interactive setup wizard for codedocent."""
+    print("\ncodedocent \u2014 code visualization for humans\n")
+
+    path = _ask_folder()
+
+    # --- Ollama check ---
+    model = "qwen3:14b"
+    no_ai = False
+
+    print("Checking for Ollama...", end=" ", flush=True)
+    if _check_ollama():
+        print("found!")
+        models = _fetch_ollama_models()
+        if models:
+            model = _pick_model(models)
+        else:
+            print("No models found.")
+            no_ai = _ask_no_ai_fallback()
+    else:
+        print("not found.")
+        no_ai = _ask_no_ai_fallback()
+
+    # --- Mode ---
+    print("\nHow do you want to view it?")
+    print("  1. Interactive \u2014 browse in browser [default]")
+    print("  2. Full export \u2014 analyze everything, save HTML")
+    print("  3. Text tree \u2014 plain text in terminal")
+    mode_choice = input("Choice [1]: ").strip()
+
+    text = mode_choice == "3"
+    full = mode_choice == "2"
+
+    print()
+
+    return argparse.Namespace(
+        path=path,
+        text=text,
+        output="codedocent_output.html",
+        model=model,
+        no_ai=no_ai,
+        full=full,
+        port=None,
+        workers=1,
+        gui=False,
+    )
+
+
 def main() -> None:
     """Entry point for the codedocent CLI."""
     parser = argparse.ArgumentParser(
         prog="codedocent",
         description="Code visualization for non-programmers",
     )
-    parser.add_argument("path", help="Path to the directory to scan")
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Path to the directory to scan",
+    )
     parser.add_argument(
         "--text",
         action="store_true",
@@ -85,9 +182,23 @@ def main() -> None:
         default=1,
         help="Number of parallel AI workers for --full mode (default: 1)",
     )
+    parser.add_argument(
+        "--gui",
+        action="store_true",
+        help="Open GUI launcher",
+    )
 
     args = parser.parse_args()
 
+    if args.gui:
+        from codedocent.gui import main as gui_main  # pylint: disable=import-outside-toplevel  # noqa: E501
+
+        gui_main()
+        return
+
+    if args.path is None:
+        args = _run_wizard()
+
     scanned = scan_directory(args.path)
     tree = parse_directory(scanned, root=args.path)
 

codedocent/gui.py

@@ -0,0 +1,128 @@
+"""Tkinter GUI launcher for codedocent."""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+
+from codedocent.ollama_utils import check_ollama, fetch_ollama_models
+
+try:
+    import tkinter as tk
+    from tkinter import ttk, filedialog
+except ImportError:
+    tk = None  # type: ignore[assignment]
+
+_HAS_TK = tk is not None
+
+# Re-export for testability
+_check_ollama = check_ollama
+_fetch_ollama_models = fetch_ollama_models
+
+
+def _build_gui() -> None:
+    """Build and run the tkinter GUI window."""
+    root = tk.Tk()
+    root.title("codedocent")
+    root.resizable(False, False)
+
+    frame = ttk.Frame(root, padding=16)
+    frame.grid(row=0, column=0, sticky="nsew")
+
+    # --- Folder picker ---
+    ttk.Label(frame, text="Folder to analyze:").grid(
+        row=0, column=0, sticky="w", pady=(0, 4),
+    )
+
+    folder_var = tk.StringVar()
+    folder_entry = ttk.Entry(frame, textvariable=folder_var, width=40)
+    folder_entry.grid(row=1, column=0, sticky="ew", padx=(0, 6))
+
+    def _browse() -> None:
+        path = filedialog.askdirectory()
+        if path:
+            folder_var.set(path)
+
+    ttk.Button(frame, text="Browse...", command=_browse).grid(
+        row=1, column=1, sticky="w",
+    )
+
+    # --- Model dropdown ---
+    ttk.Label(frame, text="Model:").grid(
+        row=2, column=0, sticky="w", pady=(12, 4),
+    )
+
+    ollama_ok = _check_ollama()
+    models = _fetch_ollama_models() if ollama_ok else []
+
+    model_values = models if models else ["No AI"]
+    model_var = tk.StringVar(value=model_values[0])
+    model_combo = ttk.Combobox(
+        frame, textvariable=model_var, values=model_values,
+        state="readonly", width=37,
+    )
+    model_combo.grid(row=3, column=0, columnspan=2, sticky="ew")
+
+    # --- Mode selector ---
+    ttk.Label(frame, text="Mode:").grid(
+        row=4, column=0, sticky="w", pady=(12, 4),
+    )
+
+    mode_var = tk.StringVar(value="interactive")
+    modes_frame = ttk.Frame(frame)
+    modes_frame.grid(row=5, column=0, columnspan=2, sticky="w")
+
+    ttk.Radiobutton(
+        modes_frame, text="Interactive", variable=mode_var,
+        value="interactive",
+    ).pack(anchor="w")
+    ttk.Radiobutton(
+        modes_frame, text="Full export", variable=mode_var,
+        value="full",
+    ).pack(anchor="w")
+    ttk.Radiobutton(
+        modes_frame, text="Text tree", variable=mode_var,
+        value="text",
+    ).pack(anchor="w")
+
+    # --- Go button ---
+    def _go() -> None:
+        folder = folder_var.get().strip()
+        if not folder:
+            return
+
+        cmd = [sys.executable, "-m", "codedocent", folder]
+
+        selected_model = model_var.get()
+        if selected_model == "No AI":
+            cmd.append("--no-ai")
+        else:
+            cmd.extend(["--model", selected_model])
+
+        mode = mode_var.get()
+        if mode == "full":
+            cmd.append("--full")
+        elif mode == "text":
+            cmd.append("--text")
+
+        subprocess.Popen(cmd)  # pylint: disable=consider-using-with  # nosec B603  # noqa: E501
+        root.destroy()
+
+    ttk.Button(frame, text="Go", command=_go).grid(
+        row=6, column=0, columnspan=2, pady=(16, 0),
+    )
+
+    root.mainloop()
+
+
+def main() -> None:
+    """Entry point for codedocent-gui."""
+    if not _HAS_TK:
+        print("tkinter is not installed.")
+        print("Install it with: sudo apt install python3-tk")
+        raise SystemExit(1)
+    _build_gui()
+
+
+if __name__ == "__main__":
+    main()

codedocent/ollama_utils.py

@@ -0,0 +1,31 @@
+"""Shared Ollama utility functions for CLI and GUI."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+
+
+def check_ollama() -> bool:
+    """Return True if Ollama is reachable at localhost:11434."""
+    try:
+        req = urllib.request.Request(
+            "http://localhost:11434", method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=3):  # nosec B310
+            return True
+    except (OSError, urllib.error.URLError):
+        return False
+
+
+def fetch_ollama_models() -> list[str]:
+    """Fetch model names from the Ollama API."""
+    try:
+        req = urllib.request.Request(
+            "http://localhost:11434/api/tags", method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:  # nosec B310
+            data = json.loads(resp.read().decode())
+        return [m["name"] for m in data.get("models", [])]
+    except (OSError, urllib.error.URLError, json.JSONDecodeError, KeyError):
+        return []

codedocent/server.py

@@ -108,6 +108,9 @@ def do_GET(self):  # pylint: disable=invalid-name
                 self._serve_html()
             elif self.path == "/api/tree":
                 self._serve_tree()
+            elif self.path.startswith("/api/source/"):
+                node_id = self.path[len("/api/source/"):]
+                self._handle_source(node_id)
             else:
                 self.send_error(404)
 
@@ -142,6 +145,19 @@ def _serve_tree(self):
             self.end_headers()
             self.wfile.write(data)
 
+        def _handle_source(self, node_id: str):
+            if node_id not in node_lookup:
+                self.send_error(404, "Unknown node ID")
+                return
+            node = node_lookup[node_id]
+            result = {"source": node.source or ""}
+            data = json.dumps(result).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
         def _handle_analyze(self, node_id: str):
             if node_id not in node_lookup:
                 self.send_error(404, "Unknown node ID")

codedocent/templates/interactive.html

@@ -539,7 +539,7 @@ <h1 class="cd-header__title">codedocent</h1>
         callback(sourceCache[nodeId]);
         return;
     }
-    fetch('/api/analyze/' + nodeId, {method: 'POST'})
+    fetch('/api/source/' + nodeId)
         .then(function(r) { return r.json(); })
         .then(function(data) {
             if (data.source) {
@@ -871,7 +871,7 @@ <h1 class="cd-header__title">codedocent</h1>
     }
 
     // Code export buttons (for pre-analyzed nodes with summaries at load time)
-    if (!isDir && node.node_id && node.summary) {
+    if (!isDir && node.node_id) {
         cdCreateCodeActions(body, node.node_id, node.node_type, node.name, node.filepath, node.language);
     }
 

pyproject.toml

@@ -25,3 +25,4 @@ codedocent = ["templates/*.html"]
 
 [project.scripts]
 codedocent = "codedocent.cli:main"
+codedocent-gui = "codedocent.gui:main"