feat(cli): chain mat setup into repo config, add native Windows support

mat setup now configures the GitHub repository too (via a devenv shell
invocation so terraform/gh resolve on PATH), instead of silently stopping
short of it. Declining Nix falls back to a direct Terraform install rather
than skipping repo config entirely.

Adds bin/mat.ps1 for native Windows: offers WSL2 setup for full parity, or a
winget-based Terraform-only fallback if declined.

Also fixes stale ./setup-project.sh references in README/CONTRIBUTING/docs
left over from when bin/mat replaced it.

Author: mathieusouflis

CONTRIBUTING.md

@@ -37,7 +37,7 @@ This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.
    ```bash
    git remote add upstream https://github.com/your-org/your-repo.git
    ```
-4. Run `./setup-project.sh` — activates the Git hooks (validates commit messages locally before you push) and creates `.env` from `.env.example`. See [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) for what the hooks do.
+4. Run `./bin/mat setup` (native Windows without WSL2: `.\bin\mat.ps1`) — activates the Git hooks (validates commit messages locally before you push), creates `.env` from `.env.example`, and sets up the reproducible dev shell (Nix/direnv/devenv). See [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) for what the hooks do.
 5. Follow the full setup guide: [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md)
 
 ---

README.md

@@ -39,9 +39,11 @@ Describe the problem this project solves, its main features, and any key design
 ```bash
 git clone https://github.com/your-org/your-repo.git
 cd your-repo
-./setup-project.sh   # activates Git hooks, creates .env from .env.example
+./bin/mat setup   # Git hooks, .env, dev shell (Nix/direnv/devenv), repo config
 ```
 
+On native Windows (no WSL2), run `.\bin\mat.ps1` instead.
+
 Full setup guide (prerequisites, dependency install, dev server): [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md).
 
 ---

bin/mat

@@ -42,14 +42,79 @@ ensure_nix() {
 
   warn "Nix is not installed. It's required for the reproducible dev shell (direnv + devenv)."
   if ! confirm "Install Nix now via the Determinate Systems installer?"; then
-    warn "Skipping Nix. Git hooks and .env will still be set up below, but the dev shell (mat/terraform/etc.) won't be available until you install Nix and re-run 'mat setup'."
+    warn "Skipping Nix — falling back to a direct Terraform install instead."
     return 1
   fi
 
   info "Installing Nix (this will prompt for your password)..."
   curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-  warn "Nix installed. Open a new terminal (or source your shell profile) so the 'nix' command is on PATH, then re-run 'mat setup'."
-  return 1
+  ok "Nix installed."
+  warn "Open a new terminal (or source your shell profile) so the 'nix' command is on PATH, then re-run 'mat setup' to continue."
+  # Nothing further can run in this process (nix isn't on this shell's PATH
+  # yet), and treating this the same as a decline would wrongly trigger the
+  # no-nix fallback right after a successful install. Just stop here.
+  exit 0
+}
+
+##### TERRAFORM (no-nix fallback) #####
+ensure_terraform_direct() {
+  if command -v terraform >/dev/null 2>&1; then
+    ok "Terraform already installed."
+    return 0
+  fi
+
+  if ! confirm "Terraform is not installed. Install it now (direct download, no Nix/sudo required)?"; then
+    warn "Skipping Terraform install. Re-run 'mat setup' once it's available, or install it yourself and run 'mat repo'."
+    return 1
+  fi
+
+  if command -v brew >/dev/null 2>&1; then
+    info "Installing Terraform via Homebrew..."
+    brew install hashicorp/tap/terraform
+    return 0
+  fi
+
+  local os arch
+  case "$(uname -s)" in
+    Darwin) os="darwin" ;;
+    Linux) os="linux" ;;
+    *)
+      warn "No direct-download path for this OS. Install manually: https://developer.hashicorp.com/terraform/install"
+      return 1
+      ;;
+  esac
+  case "$(uname -m)" in
+    x86_64 | amd64) arch="amd64" ;;
+    arm64 | aarch64) arch="arm64" ;;
+    *)
+      warn "No direct-download path for architecture $(uname -m). Install manually: https://developer.hashicorp.com/terraform/install"
+      return 1
+      ;;
+  esac
+
+  # Pinned rather than queried dynamically (no jq/reliable version API without
+  # extra dependencies here) — bump periodically.
+  local version="1.15.7"
+  local install_dir="$HOME/.local/bin"
+  local tmp
+  tmp="$(mktemp -d)"
+
+  info "Downloading Terraform ${version} (${os}/${arch})..."
+  curl -sSfL -o "$tmp/terraform.zip" \
+    "https://releases.hashicorp.com/terraform/${version}/terraform_${version}_${os}_${arch}.zip"
+  mkdir -p "$install_dir"
+  unzip -oq "$tmp/terraform.zip" -d "$install_dir"
+  chmod +x "$install_dir/terraform"
+  rm -rf "$tmp"
+
+  if ! echo ":$PATH:" | grep -q ":$install_dir:"; then
+    warn "Installed to $install_dir, which isn't on PATH yet. Add this to your shell rc, then restart your shell:"
+    echo "     export PATH=\"$install_dir:\$PATH\""
+    export PATH="$install_dir:$PATH"
+    ok "Added it to PATH for the rest of this run."
+  fi
+
+  ok "Terraform installed."
 }
 
 ##### DIRENV #####
@@ -64,8 +129,10 @@ ensure_direnv() {
     nix profile install nixpkgs#direnv
   fi
 
-  local hook_line="eval \"\$(direnv hook $(basename "${SHELL:-bash}"))\""
-  local rc_file="$HOME/.$(basename "${SHELL:-bash}")rc"
+  local shell_name
+  shell_name="$(basename "${SHELL:-bash}")"
+  local hook_line="eval \"\$(direnv hook $shell_name)\""
+  local rc_file="$HOME/.${shell_name}rc"
   if [ -f "$rc_file" ] && grep -qF "direnv hook" "$rc_file"; then
     ok "direnv shell hook already present in $rc_file."
   else
@@ -148,8 +215,10 @@ cmd_repo() {
   # argument: guided flow with an interactive confirm before applying.
   local action="${1:-guided}"
 
-  if ! command -v terraform >/dev/null 2>&1 || ! command -v gh >/dev/null 2>&1; then
-    warn "terraform and/or gh are missing. Run 'mat setup' first, then re-run this from inside the dev shell."
+  # gh is optional — terraform/setup.sh falls back to an interactive token
+  # prompt when it's missing or not logged in.
+  if ! command -v terraform >/dev/null 2>&1; then
+    warn "terraform is missing. Run 'mat setup' first."
     exit 1
   fi
 
@@ -183,7 +252,7 @@ cmd_setup() {
   local os
   os="$(detect_os)"
   if [ "$os" = "unsupported" ]; then
-    warn "Unrecognized OS. Nix/devenv support macOS and Linux (including WSL2) — on native Windows, install WSL2 first and run 'mat setup' from inside it."
+    warn "Unrecognized OS. On native Windows, use bin/mat.ps1 instead (it offers WSL2, or a no-Nix Terraform-only fallback)."
   fi
 
   info "Git hooks and .env (no Nix required for these)"
@@ -197,7 +266,24 @@ cmd_setup() {
     ensure_devenv || true
     if command -v direnv >/dev/null 2>&1; then
       direnv allow "$REPO_ROOT"
-      ok "Ran 'direnv allow' — cd out and back into this directory to enter the dev shell."
+      ok "Ran 'direnv allow'."
+    fi
+
+    echo
+    info "Configuring the GitHub repository (inside the devenv shell)"
+    if command -v devenv >/dev/null 2>&1; then
+      # terraform/gh only exist on PATH inside the devenv shell (declared in
+      # devenv.nix's packages) — a bare 'terraform' call here would fail even
+      # though nix/direnv/devenv are all now installed.
+      devenv shell -- ./bin/mat repo
+    else
+      warn "devenv isn't available — skipping repo config. Re-run 'mat setup' once it is, or run 'mat repo' yourself from inside the dev shell."
+    fi
+  else
+    echo
+    info "Falling back to a direct Terraform install (no reproducible dev shell)"
+    if ensure_terraform_direct; then
+      cmd_repo
     fi
   fi
 
@@ -211,13 +297,18 @@ usage() {
 Usage: mat <command>
 
 Commands:
-  setup           Full local onboarding: Nix, direnv, devenv, Git hooks, .env
+  setup           Full local onboarding: Nix, direnv, devenv, Git hooks, .env,
+                  then configures the GitHub repository via terraform (or a
+                  direct Terraform install if you skip Nix)
   repo            Configure the GitHub repository via terraform (branch
                   protection, merge settings, collaborators, environments) —
                   guided, asks before applying
   repo plan       Same, but only shows the plan (no prompt, no apply)
   repo apply      Applies the last plan (no prompt) — for scripted use once
                   you've already reviewed a 'repo plan'
+
+On native Windows (no WSL2), use bin/mat.ps1 instead — this script requires
+bash.
 EOF
 }
 

bin/mat.ps1

@@ -0,0 +1,153 @@
+# mat.ps1 — native Windows entrypoint. Nix/direnv/devenv only run inside
+# WSL2, so this script's real job is: get you into WSL2 (where bin/mat gives
+# you the full reproducible dev shell), or — if you decline — fall back to a
+# Terraform-only path that skips the reproducible shell entirely.
+#
+# This is a separate, smaller reimplementation of bin/mat's repo-config
+# mechanics, not a wrapper around it — bin/mat is bash and won't run natively
+# on Windows. Keep the two in sync by hand if the terraform flow changes.
+
+$ErrorActionPreference = "Stop"
+$RepoRoot = Split-Path -Parent $PSScriptRoot
+
+function Confirm-Action {
+    param([string]$Prompt)
+    $reply = Read-Host "$Prompt [y/N]"
+    return $reply -match '^[Yy]$'
+}
+
+function Test-Wsl2 {
+    try {
+        wsl.exe -l -v *> $null
+        return $LASTEXITCODE -eq 0
+    } catch {
+        return $false
+    }
+}
+
+function Enter-Wsl2Path {
+    Write-Host "-> WSL2"
+    if (Test-Wsl2) {
+        Write-Host "   WSL2 is already installed. Open a WSL2 terminal (e.g. Ubuntu) in this repo and run: ./bin/mat setup"
+        return $true
+    }
+    if (Confirm-Action "WSL2 is not installed. Install it now (requires a restart)?") {
+        wsl --install
+        Write-Host "!! Restart your computer, then open a WSL2 terminal (e.g. Ubuntu) in this repo and run: ./bin/mat setup"
+        exit 0
+    }
+    return $false
+}
+
+function Set-GitHooksAndEnv {
+    Push-Location $RepoRoot
+    try {
+        $hooksPath = git config --local --get core.hooksPath 2>$null
+        if ($hooksPath -eq ".githooks") {
+            Write-Host "   Git hooks already activated."
+        } else {
+            git config core.hooksPath .githooks
+            Write-Host "   Activated Git hooks (core.hooksPath = .githooks)."
+        }
+
+        if (Test-Path ".env") {
+            Write-Host "   .env already exists, leaving it alone."
+        } else {
+            Copy-Item ".env.example" ".env"
+            Write-Host "   Created .env from .env.example — fill in the values before running the project."
+        }
+    } finally {
+        Pop-Location
+    }
+}
+
+function Install-TerraformWinget {
+    if (Get-Command terraform -ErrorAction SilentlyContinue) {
+        Write-Host "   Terraform already installed."
+        return $true
+    }
+    if (-not (Confirm-Action "Terraform is not installed. Install it now via winget?")) {
+        Write-Host "!! Skipping Terraform install. Re-run bin/mat.ps1 once it's available, or install it yourself."
+        return $false
+    }
+    winget install --id Hashicorp.Terraform -e --accept-source-agreements --accept-package-agreements
+    return $true
+}
+
+function Get-OriginSlug {
+    $url = git -C $RepoRoot remote get-url origin 2>$null
+    if (-not $url) { return $null }
+    if ($url -match '[:/]([^/]+)/([^/.]+?)(\.git)?$') {
+        return "$($Matches[1])/$($Matches[2])"
+    }
+    return $null
+}
+
+function Get-GitHubToken {
+    if (Get-Command gh -ErrorAction SilentlyContinue) {
+        $token = gh auth token 2>$null
+        if ($token) {
+            Write-Host "   Using GitHub token from 'gh auth token'."
+            return $token
+        }
+    }
+    $secure = Read-Host "GitHub token (repo admin scope)" -AsSecureString
+    return [Runtime.InteropServices.Marshal]::PtrToStringAuto(
+        [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure))
+}
+
+function Invoke-RepoApply {
+    $slug = Get-OriginSlug
+    if (-not $slug) {
+        Write-Host "!! Couldn't determine owner/repo from 'git remote get-url origin'."
+        return
+    }
+    $owner, $repo = $slug -split '/', 2
+
+    Write-Host "-> Configuring GitHub repository: $slug"
+    $tfvarsPath = Join-Path $RepoRoot "terraform\terraform.tfvars"
+    @"
+repository_owner = "$owner"
+repository_name  = "$repo"
+"@ | Set-Content -Path $tfvarsPath
+    Write-Host "   Wrote terraform/terraform.tfvars"
+
+    $env:GITHUB_TOKEN = Get-GitHubToken
+
+    Push-Location (Join-Path $RepoRoot "terraform")
+    try {
+        terraform init | Out-Host
+
+        $state = terraform state list 2>$null
+        if (-not ($state -contains "module.github_repository.github_repository.this")) {
+            Write-Host "-> Importing the existing repository into terraform state..."
+            terraform import "module.github_repository.github_repository.this" $repo | Out-Host
+        }
+
+        terraform plan | Out-Host
+
+        if (Confirm-Action "Apply these changes to $slug now?") {
+            terraform apply | Out-Host
+        } else {
+            Write-Host "!! Skipped apply. Re-run bin/mat.ps1, or 'terraform apply' from terraform/, when ready."
+        }
+    } finally {
+        Pop-Location
+    }
+}
+
+##### MAIN #####
+Write-Host "-> Git hooks and .env (no Nix required for these)"
+Set-GitHooksAndEnv
+
+Write-Host ""
+if (-not (Enter-Wsl2Path)) {
+    Write-Host ""
+    Write-Host "-> Falling back to a direct Terraform install (no reproducible dev shell)"
+    if (Install-TerraformWinget) {
+        Invoke-RepoApply
+    }
+}
+
+Write-Host ""
+Write-Host "-> Setup complete. Full guide: docs/product-code/tutorials/getting-started.md"

docs/team-process/how-to/activate-git-hooks.md

@@ -11,8 +11,9 @@ This repo ships two shell-based hooks under `.githooks/` — no runtime or depen
 
 ## Steps
 
-Running `./setup-project.sh` from the repository root does this for you, along
-with the rest of local project setup. To activate just the hooks by hand:
+Running `./bin/mat setup` (or `.\bin\mat.ps1` on native Windows) from the
+repository root does this for you, along with the rest of local project
+setup. To activate just the hooks by hand:
 
 ```bash
 git config core.hooksPath .githooks

terraform/README.md

@@ -36,15 +36,21 @@ variables, without touching the module itself.
 
 ## Running
 
-Easiest path — `mat repo` (from `bin/mat`) detects the owner/repo from
-`git remote`, writes `terraform/terraform.tfvars`, runs `init`, imports the
-repo into state if it isn't already there, shows the plan, and asks before
-applying:
+`./bin/mat setup` already chains into this automatically on first-time
+onboarding (inside the devenv shell if you have Nix, or via a direct
+Terraform install if you don't — see `bin/mat`'s `cmd_setup`). To (re-)run it
+directly at any other time — `mat repo` (from `bin/mat`, once inside the dev
+shell) detects the owner/repo from `git remote`, writes
+`terraform/terraform.tfvars`, runs `init`, imports the repo into state if it
+isn't already there, shows the plan, and asks before applying:
 
 ```bash
 mat repo
 ```
 
+On native Windows without WSL2, `bin/mat.ps1` reimplements this same flow
+directly in PowerShell (bin/mat itself needs bash).
+
 Or drive the underlying pieces yourself. `terraform/setup.sh` is the thin
 wrapper that sources a token from `gh` if you're logged in, or prompts for
 one otherwise: