Initial commit: WinMacKeys v0.1.0

Author: ushakov-d

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = crlf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.ini]
+indent_size = 0

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint PowerShell
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run PSScriptAnalyzer
+        shell: pwsh
+        run: |
+          Set-PSRepository PSGallery -InstallationPolicy Trusted
+          Install-Module PSScriptAnalyzer -Force -Scope CurrentUser
+          $results = Invoke-ScriptAnalyzer -Path scripts -Recurse -Severity Warning, Error -Settings .\PSScriptAnalyzerSettings.psd1
+          if ($results) { $results | Format-Table -AutoSize | Out-String | Write-Host }
+          $errors = @($results | Where-Object { $_.Severity -eq 'Error' })
+          if ($errors.Count -gt 0) { throw "PSScriptAnalyzer reported $($errors.Count) error(s)." }
+          Write-Host 'PSScriptAnalyzer: OK' -ForegroundColor Green

.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build & publish
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Compiles src\WinMacKeys.ahk into a standalone .exe using the official
+      # AutoHotkey v2 base + the Ahk2Exe compiler, both fetched at build time
+      # (latest releases, so no fragile hard-coded URLs).
+      - name: Build WinMacKeys.exe
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $hdr  = @{ Authorization = "Bearer $env:GH_TOKEN"; 'User-Agent' = 'winmac-keys-ci' }
+          $work = Join-Path $env:RUNNER_TEMP 'ahkbuild'
+          New-Item -ItemType Directory -Force -Path $work | Out-Null
+
+          Write-Host 'Fetching AutoHotkey v2 (base)...'
+          $ahkRel   = Invoke-RestMethod 'https://api.github.com/repos/AutoHotkey/AutoHotkey/releases/latest' -Headers $hdr
+          $ahkAsset = $ahkRel.assets | Where-Object { $_.name -like 'AutoHotkey_*.zip' } | Select-Object -First 1
+          Invoke-WebRequest $ahkAsset.browser_download_url -Headers $hdr -OutFile "$work\ahk.zip"
+          Expand-Archive "$work\ahk.zip" -DestinationPath "$work\ahk" -Force
+          $base = (Get-ChildItem "$work\ahk" -Recurse -Filter 'AutoHotkey64.exe' | Select-Object -First 1).FullName
+
+          Write-Host 'Fetching Ahk2Exe (compiler)...'
+          $c2Rel   = Invoke-RestMethod 'https://api.github.com/repos/AutoHotkey/Ahk2Exe/releases/latest' -Headers $hdr
+          $c2Asset = $c2Rel.assets | Where-Object { $_.name -like '*.zip' } | Select-Object -First 1
+          Invoke-WebRequest $c2Asset.browser_download_url -Headers $hdr -OutFile "$work\ahk2exe.zip"
+          Expand-Archive "$work\ahk2exe.zip" -DestinationPath "$work\ahk2exe" -Force
+          $ahk2exe = (Get-ChildItem "$work\ahk2exe" -Recurse -Filter 'Ahk2Exe.exe' | Select-Object -First 1).FullName
+
+          New-Item -ItemType Directory -Force -Path 'dist' | Out-Null
+          & $ahk2exe /in 'src\WinMacKeys.ahk' /out 'dist\WinMacKeys.exe' /base $base
+          if ($LASTEXITCODE -ne 0 -or -not (Test-Path 'dist\WinMacKeys.exe')) {
+              throw "Ahk2Exe failed (exit $LASTEXITCODE)."
+          }
+          Write-Host 'Built dist\WinMacKeys.exe' -ForegroundColor Green
+
+      - name: Package release zip
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $stage = 'dist\WinMacKeys'
+          New-Item -ItemType Directory -Force -Path $stage | Out-Null
+          Copy-Item 'dist\WinMacKeys.exe'              $stage
+          Copy-Item 'scripts\install.ps1'              $stage
+          Copy-Item 'scripts\uninstall.ps1'            $stage
+          Copy-Item 'config\winmac-keys.example.ini'   $stage
+          Copy-Item 'README.md'                        $stage
+          Copy-Item 'LICENSE'                          $stage
+          $zip = "dist\WinMacKeys-$env:GITHUB_REF_NAME.zip"
+          Compress-Archive -Path "$stage\*" -DestinationPath $zip -Force
+          (Get-FileHash $zip -Algorithm SHA256).Hash | Out-File "$zip.sha256" -Encoding ascii
+          Write-Host "Packaged $zip" -ForegroundColor Green
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/WinMacKeys-*.zip
+            dist/WinMacKeys-*.zip.sha256
+            dist/WinMacKeys.exe

.gitignore

@@ -0,0 +1,14 @@
+# Build output
+/dist/
+*.exe
+
+# Logs / temp
+*.log
+*.tmp
+Thumbs.db
+desktop.ini
+
+# Editor / OS
+.vs/
+.idea/
+.vscode/

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-07
+
+### Added
+- Switch input language with a single key (default `Caps Lock`); `Shift+Caps Lock`
+  keeps the normal Caps Lock behaviour.
+- Optional `Ctrl ⇄ Win` swap (`off` / `left` / `full`).
+- Map a Mac-style chord to the Windows region screenshot (`Win+Shift+S`); default
+  `Ctrl+Shift+Win+4` to match common Keychron Mac macro keys.
+- Generic key remaps (`[remap]`), e.g. `CapsLock = Escape`.
+- App / file / URL launcher hotkeys (`[run]`).
+- Hyper key (`Ctrl+Alt+Shift+Win`) with `[hyper]` + `[hyper_run]` bindings.
+- macOS-style text navigation (`[mac_text_nav]`).
+- INI-based configuration in `%APPDATA%\WinMacKeys\config.ini`.
+- Tray menu: Suspend, Edit config, Reload, Exit.
+- `install.ps1` / `uninstall.ps1` with a SID-based logon Scheduled Task.
+- GitHub Actions: PowerShell lint (CI) and `.exe` build + release on tags.
+
+[Unreleased]: https://github.com/ushakov-d/winmac-keys/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ushakov-d/winmac-keys/releases/tag/v0.1.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ushakov-d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PSScriptAnalyzerSettings.psd1

@@ -0,0 +1,8 @@
+@{
+    # install.ps1 / uninstall.ps1 are user-facing installer scripts whose whole
+    # job is to print colored progress to the console. Write-Host is the right
+    # tool for that here, so we deliberately silence PSAvoidUsingWriteHost.
+    ExcludeRules = @(
+        'PSAvoidUsingWriteHost'
+    )
+}

README.md

@@ -0,0 +1,164 @@
+# WinMacKeys
+
+> Mac-style keyboard tweaks for Windows 11 — switch input language with **Caps Lock**, optional **Ctrl ⇄ Win** swap, and a Mac-style **region screenshot** chord.
+
+[![CI](https://github.com/ushakov-d/winmac-keys/actions/workflows/ci.yml/badge.svg)](https://github.com/ushakov-d/winmac-keys/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/ushakov-d/winmac-keys?sort=semver)](https://github.com/ushakov-d/winmac-keys/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+🇷🇺 [Документация на русском](README.ru.md)
+
+---
+
+## Features
+
+| Feature | Default | What it does |
+| --- | --- | --- |
+| **Language switch** | `Caps Lock` | One key toggles the input language. `Shift+Caps Lock` keeps the normal Caps Lock. |
+| **Ctrl ⇄ Win swap** | off | Make the bottom-row modifiers feel like macOS. `off` / `left` / `full`. |
+| **Region screenshot** | `Ctrl+Shift+Win+4` | Maps a Mac-style chord to the Windows region capture (`Win+Shift+S`). Handy for Keychron Mac macro keys. |
+| **Custom remaps** | off | Remap any key to any key, e.g. `CapsLock = Escape`, via `[remap]`. |
+| **App / URL launcher** | off | Bind a hotkey to launch an app, file or URL via `[run]`. |
+| **Hyper key** | off | Turn a key into `Ctrl+Alt+Shift+Win` and bind `hyper + X` shortcuts. |
+| **Mac text navigation** | off | `Win+←/→` = Home/End, `Win+↑/↓` = doc start/end, `Alt+←/→` = word. |
+
+Everything is driven by a small INI file, so each feature can be turned on/off without touching code.
+
+> Windows has **no built-in option** to switch the input language with Caps Lock — that is the main reason this tool exists.
+
+## Why a tool and not just registry tweaks?
+
+The native Windows language-switch hotkeys are limited to `Alt+Shift`, `Ctrl+Shift`, the grave accent and `Win+Space`. Caps Lock is simply not an option in the OS UI. WinMacKeys adds that (and a couple of related niceties) as a tiny [AutoHotkey v2](https://www.autohotkey.com/) layer.
+
+## How it works
+
+Under the hood it's a tiny [AutoHotkey v2](https://www.autohotkey.com/) script that intercepts key presses and substitutes the action you configured. All settings live in a plain `config.ini` — change a value, hit **Reload** in the tray menu, done; you never edit code. The installer copies the program, creates the config and registers a **logon Scheduled Task** so it starts with Windows; the uninstaller removes everything. No AutoHotkey installed? Each release ships a standalone `.exe` that runs without dependencies.
+
+In one line: *a thin layer over Windows that puts Mac-style habits (Caps = language, Ctrl↔Win, a screenshot chord, plus your own remaps) onto the keyboard and starts itself at logon.*
+
+## Install
+
+### Option A — from a release (recommended)
+
+1. Download the latest `WinMacKeys-vX.Y.Z.zip` from [Releases](https://github.com/ushakov-d/winmac-keys/releases) and unzip it.
+2. In the unzipped folder, run:
+
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File .\install.ps1
+   ```
+
+The release bundles a standalone `WinMacKeys.exe`, so **AutoHotkey is not required**.
+
+### Option B — from source
+
+```powershell
+git clone https://github.com/ushakov-d/winmac-keys.git
+cd winmac-keys
+powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
+```
+
+From source the installer will install AutoHotkey v2 via `winget` if it is missing.
+
+The installer:
+
+- copies the program to `%LOCALAPPDATA%\Programs\WinMacKeys`,
+- writes a default config to `%APPDATA%\WinMacKeys\config.ini` (never overwrites an existing one),
+- registers a **logon Scheduled Task** so it starts automatically (one UAC prompt),
+- starts it right away.
+
+Run with `-NoAutostart` to skip the Scheduled Task.
+
+## Configuration
+
+Every feature is switched on/off in this one text file — **no code changes**. Each `[section]` is independent: set `enabled = true/false` (or `mode = ...` for the swap); the `[remap]`, `[run]` and `[hyper_run]` sections are just lists of lines, and an **empty section means off**. Defaults: language switch and region screenshot **on**, everything else **off**.
+
+Edit `%APPDATA%\WinMacKeys\config.ini`, then pick **Reload** from the tray menu — changes apply instantly.
+
+```ini
+[language]
+; method: altshift | ctrlshift | winspace
+enabled = true
+hotkey = CapsLock
+method = altshift
+shift_toggles_capslock = true
+
+[swap_ctrl_win]
+; mode: off | left | full
+mode = off
+
+[screenshot]
+; hotkeys: semicolon-separated list; ^=Ctrl +=Shift #=Win  (^+#4 = Ctrl+Shift+Win+4)
+enabled = true
+hotkeys = ^+#4
+
+[remap]
+; one "from = to" per line
+CapsLock = Escape
+
+[run]
+; "hotkey = command"
+#t = wt.exe
+^!c = https://www.google.com
+
+[hyper]
+; turn a key into Ctrl+Alt+Shift+Win, then bind hyper+X in [hyper_run]
+enabled = false
+key = CapsLock
+
+[hyper_run]
+; <key> = command  (fires while the hyper key is held)
+e = explorer.exe
+
+[mac_text_nav]
+; Win = Cmd. NOTE: overrides Win+Arrow window snapping while enabled
+enabled = false
+```
+
+See [`config/winmac-keys.example.ini`](config/winmac-keys.example.ini) for the fully commented reference. New sections (`remap`, `run`, `hyper`, `mac_text_nav`) ship **disabled/empty**, so they change nothing until you opt in.
+
+> Put comments on their own line (starting with `;`), not after a value — Windows INI keeps everything after `=` as the value. Hotkeys use [AutoHotkey modifier syntax](https://www.autohotkey.com/docs/v2/Hotkeys.htm): `^` Ctrl, `!` Alt, `+` Shift, `#` Win.
+
+## Tray menu
+
+A tray icon provides **Suspend hotkeys**, **Edit config**, **Reload** and **Exit**.
+To run without a tray icon, add `#NoTrayIcon` to the top of `WinMacKeys.ahk` (source build).
+
+## Uninstall
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\uninstall.ps1
+# add -RemoveConfig to also delete your config.ini
+```
+
+## How autostart works
+
+A per-user **Scheduled Task** (`AtLogon`, 5-second delay, highest privileges) launches the app. This is more reliable than the Startup folder, and running elevated lets the remaps work even in elevated windows. The task principal is keyed by **SID**, so it keeps working if the account is renamed.
+
+## Notes & limitations
+
+- **Unsigned executable.** The released `.exe` is not code-signed, so SmartScreen may warn on first run (*More info → Run anyway*). Each release ships a `.sha256` checksum; or run from source if you prefer.
+- **Ctrl ⇄ Win swap** moves `Ctrl+C/V/Z` onto the former Win key — that is the point of the swap, but it surprises people, so it is **off by default**.
+- **Administrator step.** Registering the logon task needs one UAC prompt. Use an account that is a local administrator (typical on personal PCs); if you elevate with a *different* admin account, the task is registered for that account. Use `-NoAutostart` to skip it entirely.
+- Works with Cyrillic / spaced user names (paths are resolved from environment variables and files are written as UTF-8). See **Compatibility** below.
+
+## Compatibility
+
+- **Tested on:** Windows 11 Pro **25H2** (build 26200.8457), x64 — with AutoHotkey **v2.0.26** and Windows PowerShell **5.1**.
+- **Should also work on:** Windows 10 and 11 (x64). AutoHotkey v2 runs on Windows 7+ and the features rely on standard OS shortcuts, so other recent builds are expected to work — just not verified by us yet.
+- **Requirements:**
+  - `Win+Shift+S` region screenshot needs the Snipping Tool (Windows 10 1809+, standard on 10/11).
+  - Installing **from source** uses `winget` to fetch AutoHotkey (Windows 10 1709+ / App Installer). The release `.exe` needs neither winget nor AutoHotkey.
+  - 64-bit Windows (the bundled build is x64); Windows PowerShell 5.1 (ships with Windows) or newer.
+
+## Build locally
+
+```powershell
+# requires AutoHotkey v2 + Ahk2Exe
+Ahk2Exe.exe /in src\WinMacKeys.ahk /out dist\WinMacKeys.exe /base AutoHotkey64.exe
+```
+
+CI builds the `.exe` and publishes a release automatically when a `vX.Y.Z` tag is pushed.
+
+## License
+
+[MIT](LICENSE)