quickhatch 0.1.0__tar.gz

quickhatch-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Jan Bartos is the sole code owner for the official QuickHatch repository.
+# To enforce this on GitHub, enable branch protection for `main` and require
+# review from Code Owners before merging pull requests.
+* @JanBartos6

quickhatch-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# GitHub shows these links in the Sponsor button.
+github: [JanBartos6]
+ko_fi: janbartos6

quickhatch-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please give us enough info to reproduce.
+
+        **Security issues:** do NOT use this form — see [SECURITY.md](https://github.com/JanBartos6/QuickHatch/blob/main/SECURITY.md).
+
+  - type: input
+    id: version
+    attributes:
+      label: QuickHatch version
+      placeholder: e.g. 0.1.0 (run `python -m quickhatch --version` if available, or check the GUI footer)
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Host OS
+      description: The machine running QuickHatch
+      placeholder: e.g. Windows 11 23H2
+    validations:
+      required: true
+
+  - type: input
+    id: target
+    attributes:
+      label: Target Linux distro (if relevant)
+      placeholder: e.g. Arch Linux 2026.04, fresh install in VirtualBox
+
+  - type: dropdown
+    id: ai_provider
+    attributes:
+      label: AI provider
+      options:
+        - LM Studio (local)
+        - Ollama (local)
+        - Claude API (Anthropic)
+        - OpenAI API
+        - Codex CLI
+        - Other / N/A
+    validations:
+      required: true
+
+  - type: input
+    id: model
+    attributes:
+      label: Model name
+      placeholder: e.g. google/gemma-4-26b-a4b, claude-sonnet-4-6, gpt-4o
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Agent output, console errors, terminal output. Paste as text or attach a file.
+      render: shell
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Screenshots, hypotheses, related issues — drop them here.

quickhatch-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: mailto:appdeveloper.honza@gmail.com
+    about: Please email instead of opening a public issue.
+  - name: Question or general discussion
+    url: https://github.com/JanBartos6/QuickHatch/discussions
+    about: Use Discussions for "how do I…" or "is this a good idea?"

quickhatch-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature request
+description: Suggest a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea? Tell us the problem first, then your proposed solution.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the user-facing pain point. Don't jump straight to the solution.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like QuickHatch to handle this?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other ways to solve this. Why is your proposal better?
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Mockups, links, related tools.

quickhatch-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+<!-- Thanks for contributing! -->
+
+## What this changes
+
+<!-- One or two sentences. What's different after this PR? -->
+
+## Why
+
+<!-- The motivating problem. Link an issue if there is one. -->
+
+## How to verify
+
+<!-- Steps a reviewer can run. "I tested X and Y" or "Run pytest". -->
+
+## Checklist
+
+- [ ] `pytest` passes locally
+- [ ] `ruff check src/ tests/` is clean
+- [ ] `ruff format --check src/ tests/` is clean
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]` if this is user-visible
+- [ ] No secrets, API keys, or paths from your real machine in the diff
+- [ ] I have the right to submit this work and agree to the contribution ownership/license terms in `CONTRIBUTING.md`

quickhatch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check src/ tests/
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+      - name: Run pytest
+        run: pytest -q

quickhatch-0.1.0/.github/workflows/full-matrix.yml

@@ -0,0 +1,40 @@
+name: Full test matrix
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: full-test-matrix-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  full-test:
+    name: full test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.11"
+          - os: macos-latest
+            python-version: "3.11"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run pytest
+        run: pytest -v

quickhatch-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish, for example v0.1.0"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/quickhatch
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Check tag matches package version
+        run: |
+          TAG="${{ inputs.tag }}"
+          VERSION="${TAG#v}"
+          PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$VERSION" != "$PKG" ]; then
+            echo "Tag $TAG does not match pyproject.toml version $PKG"; exit 1
+          fi
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

quickhatch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # so changelog generation can see history
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Check tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "Tag v$TAG does not match pyproject.toml version $PKG"; exit 1
+          fi
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          # Capture from "## [VERSION]" up to the next "## ["
+          awk -v v="$VERSION" '
+            index($0, "## [" v "]") == 1 { capture=1; next }
+            capture && /^## \[/ { exit }
+            capture { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "Release $TAG" > release-notes.md
+          fi
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          body_path: release-notes.md
+          generate_release_notes: false
+          prerelease: true

quickhatch-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.tmp/
+dist/
+build/
+.quickhatch-checkpoint.json
+*.iso
+.env
+.quickhatch/
+
+# Agent temp files
+.quickhatch-prompt.txt
+.quickhatch-agent-cmd.sh
+.quickhatch-agent-cmd.ps1
+.quickhatch-server*.log
+.codex_tmp_*
+.scrape-cache/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Claude Code working files
+.claude/

quickhatch-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=512"]
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

quickhatch-0.1.0/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to QuickHatch will be documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+No changes yet.
+
+## [0.1.0] - 2026-06-12
+
+First public alpha release.
+
+### Added
+
+- Added community recipe gallery with about 100 curated Linux desktop
+  configurations.
+- Added host-side post-install data transfer for the "keep this PC on" path:
+  selected local files or folders are copied over SSH into
+  `~/QuickHatch-Imported-Windows`, while external-drive and cloud methods stay
+  guided/manual.
+- Fresh installs now use `password` as the temporary first-login password,
+  remove the QuickHatch NOPASSWD sudo drop-in at the end of setup, and mark the
+  installed user account to require a real password change on first login.
+- Added a strict Linux desktop GUI contract test suite for promised theme,
+  icon, cursor, wallpaper, and desktop-effect elements. Strict desktop runs now
+  require each promised element to have a concrete expected value or an explicit
+  manual-follow-up reason before success can be claimed.
+- Documented contribution and fork licensing terms, made commercial-use contact
+  language visible in the README, added sponsorship links, and noted the June 4,
+  2026 real-PC Arch install driven by Gemini 3.1 Flash Lite.
+- Added commercial licensing contact email, stronger source-available license
+  terms, contribution assignment/licensing language, CODEOWNERS, and governance
+  notes for maintainer-controlled merges to `main`.
+- Added secret-pattern hygiene coverage so release sources fail tests if
+  provider-token-shaped strings are introduced into tracked release files.
+- Gallery Phase 1.5: loosened the Reddit filter so r/unixporn and DE-specific
+  subs contribute entries. The previous "median + 1 stdev" upvote gate was
+  replaced with per-subreddit absolute floors (500 for r/unixporn, 30-100 for
+  DE subs) combined with a top-40%-of-bucket rule. Reddit entries with no
+  detectable OSI license are admitted with `license_status: "unknown"` and a
+  "No license" chip in the gallery; apply logic skips them so QuickHatch does
+  not copy unlicensed work.
+
+### Highlights
+
+- Two modes: "Migrate from Windows" for fresh Linux installs on a target
+  machine, and "Customize Linux" for tuning an existing install.
+- Agentic SSH setup loop: the LLM picks one command, sees exit code plus
+  stdout/stderr, and decides the next step. It adapts to errors such as missing
+  packages, low disk space, and failed verifications.
+- Live web and image search: the analysis phase can fetch DuckDuckGo results so
+  the model gets current context on driver support, app alternatives, and
+  desktop environment screenshots.
+- End-to-end verified on Arch Linux on a real PC on June 4, 2026, driven by
+  Gemini 3.1 Flash Lite.
+- Web GUI with stepper navigation, agent feed, technical log, apps step with
+  search and compatibility badges, error states, and toast notifications.
+
+### Wizard
+
+- Welcome -> AI setup -> Preferences -> Scan -> Apps & Data -> Notes ->
+  Analysis -> Bootable USB -> SSH key -> Export -> Remote setup.
+- Scans Windows hardware, installed apps, settings, file summary, fonts,
+  browser profiles, and disk layout.
+- Apps step shows scanned apps grouped by category, searchable, with native,
+  alternative, or unknown compatibility badges.
+- Apps & Data includes a structured data-transfer choice.
+- Generates a sectioned migration plan covering distro, apps, drivers, desktop,
+  migration steps, and quick-reference summary.
+- Re-runs analysis when the user gives feedback to the agent.
+
+### AI providers
+
+- Claude API.
+- OpenAI API.
+- LM Studio, with auto-detection of loaded models via
+  `localhost:1234/v1/models`.
+- Ollama via `localhost:11434`.
+- Codex CLI launched in a separate terminal.
+
+### Remote setup
+
+- SSH-based agent loop with Stop button.
+- Test-connection button to verify SSH before launch.
+- `host:port` format supported for the IP input.
+- Setup agent reads the analysis suggestions as the blueprint instead of
+  re-planning from scratch.
+- Final audit and support-bundle paths redact secret-bearing values before
+  exposing run artifacts.
+
+### Repo and tooling
+
+- 2663 pytest tests covering parsers, BridgeState, app mapping, prompt builders,
+  search execution, setup orchestration, desktop GUI contracts, support bundle
+  redaction, release smoke checks, and HTTP endpoints.
+- GitHub Actions CI runs Ruff lint, Ruff format check, and pytest on normal
+  pushes and pull requests.
+- Manual "Full test matrix" workflow covers supported OS/Python combinations.
+- GitHub Actions release workflow builds artifacts and creates a GitHub Release
+  on `v*.*.*` tags, with PyPI trusted publishing configured in the workflow.
+- `.pre-commit-config.yaml` for Ruff and standard hygiene hooks.
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, issue templates,
+  PR template, `GOVERNANCE.md`, `.github/CODEOWNERS`, and funding metadata.
+- Docs: `docs/ARCHITECTURE.md`, `docs/testing-in-vm.md`,
+  `docs/model-recommendations.md`, and `docs/troubleshooting.md`.
+- Source-available personal-use license with commercial use by separate written
+  arrangement.
+
+### Known limitations
+
+- Data transfer is method-dependent. If the Windows/host PC stays online during
+  remote setup, QuickHatch can copy selected scanned folders to the installed
+  Linux user after setup. External-drive and cloud-sync methods remain
+  guided/manual.
+- No automated USB flashing. The "Bootable USB" step is a guided walkthrough;
+  use Rufus, Ventoy, or balenaEtcher yourself.
+- GPU passthrough is not handled in VirtualBox testing.
+- Wayland plus VirtualBox mouse integration can be flaky without Guest
+  Additions.
+- The setup agent requires SSH key authentication. Password-only SSH is not
+  supported.
+- Arch is the most tested distro. Fedora and Ubuntu should work; other distros
+  are at your own risk.
+- Current modes are Windows-to-fresh-Linux migration and existing-Linux
+  customization. Distro-to-distro switching is not implemented.

quickhatch-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to appdeveloper.honza@gmail.com. Do not publish reports containing
+personal information in public issues or discussions. All complaints will be
+reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html