quickhatch 0.1.0__py3-none-any.whl

quickhatch/__init__.py

@@ -0,0 +1,11 @@
+"""QuickHatch - Windows-to-Linux migration wizard powered by AI."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("quickhatch")
+except PackageNotFoundError:
+    # Source checkout without an installed package (e.g. running from a clone)
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

quickhatch/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m quickhatch."""
+
+from quickhatch.cli import main
+
+if __name__ == "__main__":
+    main()

quickhatch/ai/__init__.py

@@ -0,0 +1 @@
+"""AI assistant integration modules."""

quickhatch/ai/install_primer.py

@@ -0,0 +1,337 @@
+"""Lookup + rendering for distro install primers shipped with QuickHatch.
+
+The harness agent installs the target distro from a live ISO via SSH. To
+avoid the agent hallucinating flags (e.g. ``pacstrap`` options that changed
+between Arch versions), each supported distro ships a condensed install
+primer under ``data/install_primers/``. This module resolves the user's
+chosen distro (fuzzy alias match) and returns its primer text so it can be
+injected into the remote-setup prompt.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+_PRIMER_PACKAGE = "quickhatch.data.install_primers"
+
+
+@lru_cache(maxsize=1)
+def _load_index() -> dict[str, Any]:
+    """Load the primer index. Cached on first access."""
+    try:
+        with (
+            resources.files(_PRIMER_PACKAGE)
+            .joinpath("_index.json")
+            .open("r", encoding="utf-8") as handle
+        ):
+            return json.load(handle)
+    except (OSError, json.JSONDecodeError, ModuleNotFoundError):
+        return {"version": 1, "distros": []}
+
+
+def list_supported_distros() -> list[dict[str, Any]]:
+    """Return every distro entry in the primer index."""
+    return list(_load_index().get("distros", []))
+
+
+def _normalize(value: str) -> str:
+    return value.strip().lower().replace(" ", "-").replace("_", "-").replace("!", "")
+
+
+def resolve_primer(distro: str | None, preferred: str | None = None) -> dict[str, Any] | None:
+    """Given any user-typed distro hint, find the matching primer entry.
+
+    Matches against canonical names and aliases with light normalization
+    (lowercase, hyphenate whitespace). Returns the index entry dict
+    (with file path, family, release model) or ``None`` if no match.
+
+    ``preferred`` is the user's stated distro preference — used as a
+    strong tiebreaker when the free-text hint mentions multiple distros
+    (e.g. the analysis output names Arch as the recommendation and then
+    mentions Fedora in a negative comparison). If the preferred distro
+    appears anywhere in the hint, it wins.
+    """
+    if not distro:
+        return None
+    # Defensive: callers occasionally pass non-string values (dicts from
+    # partially-parsed LLM output, Path objects, etc.). Coerce or bail.
+    if not isinstance(distro, str):
+        try:
+            distro = str(distro)
+        except Exception:
+            return None
+    needle = _normalize(distro)
+    if not needle:
+        return None
+    for entry in _load_index().get("distros", []):
+        canonical = _normalize(entry.get("canonical", ""))
+        if canonical == needle:
+            return entry
+        if any(_normalize(alias) == needle for alias in entry.get("aliases", [])):
+            return entry
+
+    # No exact match — try forgiving variants.
+    # 1. Strip "linux"/"os" suffixes the user may have appended.
+    #    ("archlinux" → "arch", "fedoralinux" → "fedora", "endeavouros" stays).
+    import re
+
+    # Only strip "linux" / "-linux" suffixes, NOT bare "os" — the latter
+    # over-strips ("chromeos" → "chrome", "archos" → "arch" which would
+    # spuriously match Arch's primer). Distro-"os" variants (endeavouros,
+    # centos) stay reachable through their explicit aliases.
+    stripped = re.sub(r"-?linux$", "", needle)
+    if stripped and stripped != needle:
+        for entry in _load_index().get("distros", []):
+            if _normalize(entry.get("canonical", "")) == stripped:
+                return entry
+            if any(_normalize(alias) == stripped for alias in entry.get("aliases", [])):
+                return entry
+
+    # Helper: is a distro token mentioned in a NEGATIVE context? The model
+    # often contrasts the pick with alternatives ("unlike Ubuntu", "not
+    # Fedora", "the bloat of distributions like Ubuntu or Fedora") — those
+    # mentions must not win the resolver.
+    def _is_negative_context(text: str, match_start: int, match_end: int) -> bool:
+        # Look back only within the current local clause. A negative cue
+        # from an earlier clause ("not fedora. go with arch") must not
+        # poison the later positive recommendation.
+        raw_window = text[max(0, match_start - 60) : match_start + 1]
+        clause_window = re.split(r"[.;:!?]", raw_window)[-1]
+        window = clause_window or raw_window
+        # Word-boundary cues so "likely" doesn't trip "like" and
+        # "Linux-Mint" doesn't trip "not". Each cue is wrapped so it
+        # matches only at word boundaries inside the hyphenated needle.
+        negative_cue_words = (
+            "unlike",
+            "not",
+            "rather",
+            "instead",
+            "avoid",
+            "such",
+            "compared",
+            "versus",
+            "vs",
+            "over",  # "chose X over Y"
+            "than",  # "better than Y"
+            "bloat",
+            "constraints",
+        )
+        for cue in negative_cue_words:
+            pattern = rf"(?:^|[^a-z0-9]){re.escape(cue)}(?:$|[^a-z0-9])"
+            if re.search(pattern, window):
+                return True
+        # "like" is ambiguous — "I'd like arch" (positive) vs
+        # "distributions like X" (negative). Only treat as negative when
+        # preceded by a list-noun within ~20 chars.
+        list_noun_like = re.compile(
+            r"(?:distributions?|distros?|systems?|options?|oses|choices?|"
+            r"alternatives?)[^a-z0-9]{1,5}like(?:$|[^a-z0-9])",
+            re.IGNORECASE,
+        )
+        if list_noun_like.search(window):
+            return True
+        return False
+
+    # 2a. STRONGEST SIGNAL: if the caller passed a preferred distro AND it
+    # appears in the text as a non-negative mention, return it. This
+    # prevents the comparison-trailing-mention bug where "Arch is better
+    # than Fedora" resolves to Fedora.
+    if preferred:
+        pref_entry: dict[str, Any] | None = None
+        pref_needle = _normalize(preferred)
+        for entry in _load_index().get("distros", []):
+            canonical = _normalize(entry.get("canonical", ""))
+            aliases = [_normalize(a) for a in entry.get("aliases", [])]
+            if pref_needle == canonical or pref_needle in aliases:
+                pref_entry = entry
+                break
+        if pref_entry is not None:
+            for candidate in [
+                _normalize(pref_entry.get("canonical", "")),
+                *(_normalize(a) for a in pref_entry.get("aliases", [])),
+            ]:
+                if not candidate:
+                    continue
+                pattern = rf"(?:^|[^a-z0-9]){re.escape(candidate)}(?:$|[^a-z0-9])"
+                for mobj in re.finditer(pattern, needle):
+                    if not _is_negative_context(needle, mobj.start(), mobj.end()):
+                        return pref_entry
+
+    # 2b. Word-boundary search within a longer free-text hint
+    #    ("I'd like arch btw" → matches "arch"). Still rejects
+    #    accidental-substring cases like "templeos" matching "eos".
+    #
+    # When multiple distros appear in the text (common when the model
+    # compares options before settling), we want the one the model
+    # ACTUALLY picks — usually the last occurrence after "recommend",
+    # "recommended", "choose", or "go with". First try a targeted
+    # recommendation-phrase scan; fall back to last-occurrence.
+    #
+    # The recommend scan now looks for ANY distro token within 80 chars
+    # after a recommendation verb — not just the immediately-next word.
+    # Previously "recommended distribution: arch linux" captured the
+    # word "distribution" (junk), failed to match, and fell through to
+    # the last-mention heuristic (which picked up "Fedora" from a
+    # negative comparison at the end of the paragraph).
+    _RECOMMEND_RE = re.compile(
+        r"(?:recommend(?:ation|ed|ing)?|i\s+suggest|i\s+pick|i\s+choose|"
+        r"go\s+with|final\s+choice[: ]|best\s+fit[: ])"
+        r"([\s\S]{0,80})",
+        re.IGNORECASE,
+    )
+    rec_matches = list(_RECOMMEND_RE.finditer(needle))
+    if rec_matches:
+        for rm in reversed(rec_matches):
+            window = rm.group(1)
+            # Recompute absolute offsets so negative-context detection
+            # works against the full needle.
+            window_start = rm.start(1)
+            for entry in _load_index().get("distros", []):
+                for candidate in (
+                    _normalize(entry.get("canonical", "")),
+                    *(_normalize(alias) for alias in entry.get("aliases", [])),
+                ):
+                    if not candidate:
+                        continue
+                    pattern = rf"(?:^|[^a-z0-9]){re.escape(candidate)}(?:$|[^a-z0-9])"
+                    m = re.search(pattern, window)
+                    if m and not _is_negative_context(
+                        needle, window_start + m.start(), window_start + m.end()
+                    ):
+                        return entry
+
+    # No recommendation phrase matched a known distro — fall back to
+    # scanning the WHOLE text but return the LAST distro mentioned that
+    # isn't in a negative context.
+    last_match: tuple[int, dict[str, Any]] | None = None
+    for entry in _load_index().get("distros", []):
+        haystack = [
+            _normalize(entry.get("canonical", "")),
+            *(_normalize(alias) for alias in entry.get("aliases", [])),
+        ]
+        for candidate in haystack:
+            if not candidate:
+                continue
+            pattern = rf"(?:^|[^a-z0-9]){re.escape(candidate)}(?:$|[^a-z0-9])"
+            for mobj in re.finditer(pattern, needle):
+                if _is_negative_context(needle, mobj.start(), mobj.end()):
+                    continue
+                if last_match is None or mobj.start() > last_match[0]:
+                    last_match = (mobj.start(), entry)
+    if last_match is not None:
+        return last_match[1]
+    return None
+
+
+def _read_primer_file(filename: str) -> str | None:
+    """Read a primer markdown file from the package data directory."""
+    if not filename:
+        return None
+    try:
+        with (
+            resources.files(_PRIMER_PACKAGE)
+            .joinpath(filename)
+            .open("r", encoding="utf-8") as handle
+        ):
+            return handle.read()
+    except (OSError, ModuleNotFoundError):
+        return None
+
+
+def load_family_text(family: str | None) -> str | None:
+    """Read a family primer by key (e.g. ``debian`` -> families/debian-family.md)."""
+    if not family:
+        return None
+    families = _load_index().get("families") or {}
+    rel = families.get(family)
+    if not rel:
+        return None
+    return _read_primer_file(rel)
+
+
+def load_primer_text(distro: str | None) -> str | None:
+    """Return the full primer Markdown for ``distro``, or None if no match.
+
+    Stitches the family primer (shared install procedure) with the distro
+    card (distro-specific values + overrides) when the distro references a
+    family. Standalone distros (NixOS, Alpine, etc.) return their card
+    directly.
+    """
+    entry = resolve_primer(distro)
+    if entry is None:
+        return None
+    card = _read_primer_file(entry.get("file", ""))
+    if card is None:
+        return None
+    family_body = load_family_text(entry.get("family"))
+    if family_body is None:
+        return card
+    # Family primer first, then distro card. Separator makes the boundary
+    # visually obvious for the LLM reading the prompt.
+    return f"{family_body}\n\n---\n\n{card}"
+
+
+def supported_distros_summary() -> str:
+    """Short Markdown list of every supported distro with one-line notes.
+
+    Used in prompts where we want to tell the LLM "these are the distros
+    we have install primers for" without injecting the full primer text.
+    """
+    lines: list[str] = ["## QuickHatch-supported distros", ""]
+    for entry in list_supported_distros():
+        canonical = entry.get("canonical", "?")
+        family = entry.get("family", "?")
+        release = entry.get("release_model", "?")
+        lines.append(f"- **{canonical}** — family: {family}, release: {release}")
+    return "\n".join(lines)
+
+
+def primer_prompt_block(distro: str | None) -> str:
+    """Wrap the selected primer in a clear header for injection into prompts.
+
+    If no distro match, returns a generic "consult distro docs" note so the
+    agent still has guidance (fall back to the LLM's general knowledge).
+    """
+    primer = load_primer_text(distro)
+    if primer is None:
+        # Don't print the literal string "None" when no distro was
+        # selected — say so explicitly instead.
+        distro_label = distro if distro else "(not selected)"
+        fallback = (
+            f"The requested distro ``{distro_label}`` is not in QuickHatch's "
+            "curated primer library. "
+            "Proceed using your training-data knowledge of that distro's "
+            "standard install procedure (live ISO → partition → install → "
+            "configure → reboot → reconnect). "
+            "If you are uncertain about a flag or command, ask the user "
+            "via the bridge chat before executing.\n\n"
+        )
+        return (
+            "== DISTRO INSTALL PRIMER (not found) ==\n\n"
+            + fallback
+            + supported_distros_summary()
+            + "\n"
+        )
+    entry = resolve_primer(distro)
+    assert entry is not None  # load_primer_text returned non-None
+    header = (
+        f"== DISTRO INSTALL PRIMER: {entry['canonical']} ==\n\n"
+        "The following Markdown is QuickHatch's curated install guide for this "
+        "distro. It is authoritative — follow the command ordering and flag "
+        "choices here rather than improvising. Placeholders in <ANGLE_BRACKETS> "
+        "must be substituted with values from the user profile (username, "
+        "hostname, target disk, timezone, public SSH key, passwords).\n\n"
+    )
+    return header + primer + "\n"
+
+
+__all__ = [
+    "list_supported_distros",
+    "load_primer_text",
+    "primer_prompt_block",
+    "resolve_primer",
+    "supported_distros_summary",
+]

quickhatch/ai/instruction_gen.py

@@ -0,0 +1,231 @@
+"""Generate the exported AI reference brief for QuickHatch bundles.
+
+This file is intentionally NOT the live analysis prompt used by the web
+wizard. The real interactive analysis/setup flow lives in
+``quickhatch.gui.server`` and now uses sectioned, structured contracts.
+
+The export bundle still benefits from a human-readable AI brief, but it
+should describe the current product behavior rather than preserve an older
+"one giant narrative prompt" model.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from quickhatch.config import UserProfile
+
+
+def _redacted_profile_dict(profile: UserProfile) -> dict[str, Any]:
+    data = asdict(profile)
+    if data.get("ai_config", {}).get("api_key"):
+        data["ai_config"]["api_key"] = "***REDACTED***"
+    return data
+
+
+def _compact_profile_json(profile: UserProfile) -> str:
+    """Smaller, export-friendly profile snapshot.
+
+    Keep the fields that matter for an external agent or manual review,
+    but don't dump every bit of scan data into a second drift-prone mega-prompt.
+    """
+    data = _redacted_profile_dict(profile)
+    prefs = data.get("preferences", {})
+    hardware = data.get("hardware", {})
+    apps = data.get("apps", [])
+    files_summary = data.get("files_summary", {})
+
+    trimmed = {
+        "preferences": prefs,
+        "ai_config": data.get("ai_config", {}),
+        "hardware": {
+            "cpu": hardware.get("cpu", ""),
+            "cpu_cores": hardware.get("cpu_cores", 0),
+            "ram_gb": hardware.get("ram_gb", 0),
+            "gpus": hardware.get("gpus", []),
+            "wifi_adapters": hardware.get("wifi_adapters", []),
+            "bluetooth": hardware.get("bluetooth", False),
+            "disks": hardware.get("disks", []),
+            "efi": hardware.get("efi", False),
+        },
+        "apps": apps[:80],
+        "apps_to_install": data.get("apps_to_install", []),
+        "windows_settings": data.get("windows_settings", {}),
+        "files_summary": {
+            "total_files": files_summary.get("total_files", 0),
+            "total_size_mb": files_summary.get("total_size_mb", 0),
+            "top_types": files_summary.get("top_types", {}),
+            "browser_profiles": files_summary.get("browser_profiles", {}),
+        },
+        "data_transfer_method": data.get("data_transfer_method", ""),
+        "data_transfer_paths": data.get("data_transfer_paths", []),
+        "data_description": data.get("data_description", ""),
+        "linux_ip": data.get("linux_ip", ""),
+        "linux_user": data.get("linux_user", ""),
+        "target_hardware_override": data.get("target_hardware_override", ""),
+        "additional_info": data.get("additional_info", ""),
+    }
+    return json.dumps(trimmed, indent=2, default=str)
+
+
+def _mode_section(profile: UserProfile) -> str:
+    prefs = profile.preferences
+    if prefs.migration_type == "customize_linux":
+        return (
+            "## Mode\n\n"
+            "Customization mode. You are acting on an already-installed Linux system.\n"
+            "Operate locally and verify changes directly on that machine.\n"
+        )
+    return (
+        "## Mode\n\n"
+        "Migration mode. QuickHatch runs from Windows, then connects to the Linux target over SSH.\n"
+        "Do not assume local execution on Linux until SSH access is ready.\n"
+    )
+
+
+def _operating_rules(profile: UserProfile) -> str:
+    prefs = profile.preferences
+    rules = [
+        "## Operating Rules",
+        "",
+        "1. Explicit user choices override stylistic preference. If the user named a distro, use that distro unless it is not a real Linux distribution.",
+        "2. Latest user feedback wins over earlier assumptions.",
+        "3. Describe and verify the full end-state, not just package installation.",
+        "4. If `gallery_picks` is non-empty, those recipes are authoritative design references. Personalize within them instead of inventing a different desktop direction.",
+        "5. When `data_transfer_method` is `keep_windows`, QuickHatch can copy selected `data_transfer_paths` from the host to the installed target after setup. For external-drive/cloud methods, only claim Linux-side preparation and instructions.",
+        "6. If `target_hardware_override` is non-empty, treat it as authoritative over scanned hardware for driver and install decisions.",
+        "7. Remote setup commands run on the Linux target. They cannot read Windows-local paths unless Windows exposes them over SSH/SMB, the disk is mounted, or the user moved the files first.",
+    ]
+    if prefs.migration_type == "customize_linux":
+        rules.append("8. In customization mode, no distro recommendation is needed.")
+    else:
+        rules.append(
+            "8. In migration mode, plan around SSH access from Windows to the Linux target."
+        )
+    return "\n".join(rules) + "\n"
+
+
+def _workflow_section(profile: UserProfile) -> str:
+    prefs = profile.preferences
+    if prefs.migration_type == "customize_linux":
+        return (
+            "## Expected Workflow\n\n"
+            "1. Inspect the current Linux setup directly.\n"
+            "2. Align the desktop with the user's look/preferences and any pinned gallery recipes.\n"
+            "3. Install requested software and configure it.\n"
+            "4. Handle drivers, locale, keyboard, fonts, and other system tuning.\n"
+            "5. Verify the resulting desktop, apps, and hardware behavior.\n"
+        )
+
+    lines = [
+        "## Expected Workflow",
+        "",
+        "1. Review the profile and clarify any missing requirements.",
+        "2. Recommend or confirm the distro choice.",
+        "3. Map requested/scanned Windows apps to Linux-native packages, alternatives, or Wine/Proton paths.",
+        "4. Plan drivers, desktop setup, data migration, and post-install verification.",
+        "5. Once SSH is ready, connect to the Linux target and apply the plan.",
+        "6. Verify apps, desktop state, and hardware before declaring completion.",
+    ]
+    if profile.preferences.gallery_picks:
+        lines.append(
+            "7. Apply the desktop direction around the pinned gallery recipe(s), not around a fresh invention."
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _bridge_section(profile: UserProfile) -> str:
+    ai = profile.ai_config
+    endpoint = ai.endpoint or ""
+    if "localhost" not in endpoint:
+        return ""
+    return (
+        "## QuickHatch Bridge API\n\n"
+        f"Base URL: `{endpoint}`\n\n"
+        "This local API is how the interactive agent reports progress and asks follow-up questions.\n"
+        "The current live analysis flow is sectioned (`distro`, `apps`, `drivers`, `desktop`, `plan`, `summary`, and sometimes `install_script`) rather than one giant response.\n\n"
+        "Core endpoints:\n"
+        "- `GET /api/profile` — current profile snapshot\n"
+        "- `GET /api/suggestions` — accumulated section outputs\n"
+        "- `POST /api/suggest` — add a section output or progress card\n"
+        "- `POST /api/ask` — ask the user a blocking question\n"
+        "- `POST /api/message` — post a status message\n"
+        "- `POST /api/done` — signal completion\n"
+    )
+
+
+def _gallery_section(profile: UserProfile) -> str:
+    picks = profile.preferences.gallery_picks
+    if not picks:
+        return (
+            "## Desktop Design Inputs\n\n"
+            "No gallery recipe is pinned. Use the user's desktop preferences as guidance, but keep the design grounded and reproducible.\n"
+        )
+    joined = ", ".join(f"`{item}`" for item in picks)
+    return (
+        "## Desktop Design Inputs\n\n"
+        f"Pinned gallery recipe IDs: {joined}\n\n"
+        "Treat these as the authoritative desktop references for theme / icon / font / wallpaper direction.\n"
+    )
+
+
+def _ssh_section(profile: UserProfile) -> str:
+    if not profile.ssh_public_key_path:
+        return (
+            "## SSH Access\n\n"
+            "No SSH key path is stored yet. If you need remote execution, establish SSH access first.\n"
+        )
+    priv_key = str(Path(profile.ssh_public_key_path).with_suffix(""))
+    return (
+        "## SSH Access\n\n"
+        f"- Private key on the Windows host: `{priv_key}`\n"
+        f"- Public key path: `{profile.ssh_public_key_path}`\n"
+        "- The target Linux machine must have SSH enabled and the public key installed before remote setup can proceed.\n"
+    )
+
+
+def generate_instructions(profile: UserProfile) -> str:
+    """Generate the exported AI reference brief.
+
+    This document is bundled for human review or external-agent use. It is
+    intentionally aligned with the current QuickHatch flow instead of acting as
+    a second, divergent runtime prompt.
+    """
+    prefs = profile.preferences
+    title = (
+        "# QuickHatch Reference Brief — Linux Customization\n\n"
+        if prefs.migration_type == "customize_linux"
+        else "# QuickHatch Reference Brief — Windows to Linux Migration\n\n"
+    )
+
+    intro = (
+        "This file is a reference brief exported by QuickHatch. It summarizes the user's profile,\n"
+        "the current product workflow, and the rules an external agent or human operator should follow.\n"
+        "It is not the authoritative live analysis prompt used by the web wizard; the live wizard now uses\n"
+        "sectioned prompts with structured outputs.\n\n"
+    )
+
+    sections = [
+        title + intro,
+        _mode_section(profile),
+        _operating_rules(profile),
+        _workflow_section(profile),
+        _gallery_section(profile),
+        _ssh_section(profile),
+        _bridge_section(profile),
+        "## Profile Snapshot\n\n```json\n" + _compact_profile_json(profile) + "\n```\n",
+    ]
+
+    return "\n".join(part for part in sections if part).strip() + "\n"
+
+
+def save_instructions(profile: UserProfile, output_dir: Path) -> Path:
+    """Generate and save the exported reference brief."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    instructions = generate_instructions(profile)
+    inst_path = output_dir / "MIGRATION_INSTRUCTIONS.md"
+    inst_path.write_text(instructions, encoding="utf-8")
+    return inst_path