@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/setup_ghx.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""setup_ghx.py -- consent-gated ghx proxy installer for `task setup` (#884).
+
+Wraps the `brunoborges/ghx <https://github.com/brunoborges/ghx>`_ caching
+proxy installer behind an explicit-consent prompt so the maintainer's
+``task setup`` never auto-installs network-fetched binaries by default. ghx
+is the recommended drop-in proxy for ``gh`` -- it caches read-only API
+calls so multi-agent swarms (and the deft ``scm:*`` task surface) do not
+hammer the GitHub rate limiter; v0.26.0's ``scm:*`` stub already prefers
+``ghx`` over ``gh`` at runtime via :mod:`scripts.scm`'s
+``_BINARY_PREFERENCE`` ladder when ``ghx`` is on PATH. It is maintainer and
+swarm tooling, not a consumer installer prerequisite: consumer installs require
+``gh`` for GitHub-backed workflows and transparently ignore ``ghx`` when absent.
+
+Behaviour matrix:
+
+- ``ghx`` already on PATH -> print a one-line acknowledgement, exit 0.
+- ``ghx`` missing, default (interactive) -> prompt for explicit consent
+  (default *no*); on decline print a one-line "recommended for speed"
+  note and exit 0.
+- ``ghx`` missing, ``--yes`` flag -> skip the prompt and install
+  unconditionally (CI / scripted approval path).
+- ``ghx`` missing, ``--check`` flag -> never install, never prompt;
+  print a one-line note when missing and exit 0. Used by the Taskfile
+  step so ``task setup`` is non-interactive on a clean re-run.
+
+Install dispatch is host-platform aware:
+
+- Windows -> ``pwsh -Command "irm <install.ps1> | iex"``
+- macOS / Linux -> ``curl -fsSL <install.sh> | bash``
+
+The upstream URLs come from the ghx README; both installers honour the
+upstream's documented contract. Network failures during install are
+surfaced as exit 1 (the script does NOT retry).
+
+Three-state exit (mirrors :mod:`scripts.preflight_branch` (#747) and
+:mod:`scripts.migrate_preflight` (#793)):
+
+- ``0`` -- ghx already present, user declined, or install succeeded.
+- ``1`` -- install failure (subprocess non-zero, network error, or no
+  install method available for the detected host).
+- ``2`` -- config error (e.g. ``--yes`` and ``--check`` combined).
+
+This script is intentionally pure-stdlib + ``subprocess`` so it can be
+invoked from a fresh maintainer worktree before ``uv sync`` has run.
+
+Refs #884.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: Pinned ghx version. CI workflows reference the same constant via env-var
+#: indirection (see ``.github/workflows/ci.yml``); bump both surfaces in
+#: lockstep so a future ghx security advisory only requires one edit.
+GHX_VERSION: str = "v1.5.1"
+
+#: Upstream installer URLs, pinned to :data:`GHX_VERSION` so the script the
+#: pipe-trampoline executes is the script as it existed at the pinned tag
+#: (closes Greptile #950 P2). The PowerShell installer drops binaries under
+#: ``%LOCALAPPDATA%\\ghx\\bin`` and adds them to the user PATH; the bash
+#: installer drops them under ``/usr/local/bin`` (override via
+#: ``INSTALL_DIR=...``). Pinning the URL by tag rather than ``main``
+#: prevents an upstream regression -- or a hypothetical compromise of the
+#: default branch between when CI runs and when an operator runs
+#: ``task setup:ghx`` -- from silently feeding altered shell into either
+#: trampoline. Bump in lockstep with ``.github/workflows/ci.yml``
+#: ``env.GHX_VERSION`` and the URLs under each ``Install ghx`` step.
+INSTALL_PS1_URL: str = (
+    f"https://raw.githubusercontent.com/brunoborges/ghx/{GHX_VERSION}/install.ps1"
+)
+INSTALL_SH_URL: str = (
+    f"https://raw.githubusercontent.com/brunoborges/ghx/{GHX_VERSION}/install.sh"
+)
+
+
+# ---------------------------------------------------------------------------
+# Detection
+# ---------------------------------------------------------------------------
+
+
+def ghx_present() -> bool:
+    """Return True when ``ghx`` (or ``ghx.exe`` on Windows) is on PATH.
+
+    Mirrors :func:`scripts.scm.resolve_binary` so the Taskfile-side check
+    and the ``scm:*`` runtime ladder agree on the detection contract.
+    """
+    return shutil.which("ghx") is not None
+
+
+def detect_host() -> str:
+    """Return the canonical host tag: ``windows`` / ``darwin`` / ``linux``.
+
+    Falls back to ``platform.system().lower()`` for anything else; the
+    install-dispatch branch raises a friendly error in that case.
+    """
+    system = platform.system().lower()
+    # Normalise the macOS reporting (``platform.system()`` returns
+    # ``Darwin``); other hosts come through with sensible names already.
+    if system == "darwin":
+        return "darwin"
+    if system == "windows":
+        return "windows"
+    if system == "linux":
+        return "linux"
+    return system
+
+
+# ---------------------------------------------------------------------------
+# Consent prompt
+# ---------------------------------------------------------------------------
+
+
+def prompt_consent(stream_in: object | None = None, stream_out: object | None = None) -> bool:
+    """Render an interactive y/N consent prompt; default *no*.
+
+    Args:
+        stream_in: Optional input stream override (tests inject
+            ``io.StringIO``). Defaults to ``sys.stdin``.
+        stream_out: Optional output stream override. Defaults to
+            ``sys.stdout``.
+
+    Returns:
+        True when the operator typed ``y`` / ``yes`` (case-insensitive);
+        False on empty / EOF / anything else. Default-deny matches the
+        #884 constraint that install MUST require explicit consent.
+    """
+    sin = stream_in if stream_in is not None else sys.stdin
+    sout = stream_out if stream_out is not None else sys.stdout
+    print(
+        "\n[setup_ghx] ghx is the recommended GitHub CLI cache proxy for deft "
+        "maintainers (prevents rate-limiting in multi-agent swarms; speeds up "
+        "scm:* calls). Consumer projects only require gh.",
+        file=sout,
+    )
+    print(f"[setup_ghx] Upstream: https://github.com/brunoborges/ghx ({GHX_VERSION})", file=sout)
+    print("[setup_ghx] Install ghx via the upstream installer? [y/N]: ", end="", file=sout)
+    sout.flush()
+    try:
+        # ``readline`` returns ``""`` on EOF (e.g. piped non-tty); treat
+        # as decline so a non-interactive ``task setup`` never installs by
+        # accident -- ``--yes`` is the explicit non-interactive path.
+        line = sin.readline()
+    except (EOFError, KeyboardInterrupt):
+        return False
+    answer = (line or "").strip().lower()
+    return answer in ("y", "yes")
+
+
+# ---------------------------------------------------------------------------
+# Install dispatch
+# ---------------------------------------------------------------------------
+
+
+def build_install_command(host: str) -> list[str]:
+    """Return the argv that will fetch + run the upstream installer.
+
+    Tests assert against the returned shape so a regression that changed
+    the installer URL or the shell trampoline would fail loudly here
+    rather than silently dispatching the wrong network call.
+
+    Args:
+        host: One of ``windows`` / ``darwin`` / ``linux``. Anything else
+            raises :class:`RuntimeError`.
+
+    Returns:
+        Argv list ready for :func:`subprocess.run`.
+    """
+    if host == "windows":
+        # Use ``pwsh`` (PS 7+) when available, falling back to
+        # ``powershell`` (Windows PS 5.1). The installer itself is
+        # ASCII-only per the upstream README so PS 5.1's cp1252 default
+        # does not corrupt the script body.
+        ps_bin = shutil.which("pwsh") or shutil.which("powershell") or "powershell"
+        return [
+            ps_bin,
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            f"irm {INSTALL_PS1_URL} | iex",
+        ]
+    if host in ("darwin", "linux"):
+        # ``curl | bash`` mirrors the upstream README's "Quick install
+        # script" path. ``-fsSL`` makes curl fail loud on HTTP 4xx/5xx
+        # rather than piping an HTML error page into bash.
+        return ["bash", "-c", f"curl -fsSL {INSTALL_SH_URL} | bash"]
+    raise RuntimeError(
+        f"no upstream ghx installer available for host {host!r}; "
+        "see https://github.com/brunoborges/ghx#install for manual options"
+    )
+
+
+def install_ghx(host: str, *, runner: object | None = None) -> int:
+    """Invoke the upstream installer. Returns the subprocess exit code.
+
+    Args:
+        host: The detected host tag (see :func:`detect_host`).
+        runner: Optional ``subprocess.run``-compatible callable for
+            test injection. Defaults to :func:`subprocess.run`.
+
+    Returns:
+        The installer's exit code (0 on success).
+
+    Closes Greptile #950 P1: ``GHX_VERSION`` MUST be injected into the
+    subprocess environment because the upstream ``install.sh`` /
+    ``install.ps1`` honour ``${GHX_VERSION}`` as the version-pin hook.
+    Without this, the version constant in this module was a no-op at
+    install time -- the operator-side ``task setup:ghx`` could install a
+    different binary version than the CI pre-install step despite the
+    documented lockstep contract.
+    """
+    cmd = build_install_command(host)
+    run = runner if runner is not None else subprocess.run
+    print(f"[setup_ghx] Invoking upstream installer: {' '.join(cmd)}", file=sys.stderr)
+    install_env = {**os.environ, "GHX_VERSION": GHX_VERSION}
+    proc = run(cmd, check=False, env=install_env)
+    return int(getattr(proc, "returncode", 1))
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="setup_ghx.py",
+        description=(
+            "Consent-gated installer for the ghx GitHub CLI cache proxy "
+            "(brunoborges/ghx). See #884 for the adoption rationale."
+        ),
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help=(
+            "Non-interactive consent (CI / scripted approval). Skip the y/N "
+            "prompt and install unconditionally when ghx is missing."
+        ),
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help=(
+            "Detection-only mode: print whether ghx is on PATH, then exit 0. "
+            "Never prompt, never install. Used by the Taskfile step so "
+            "`task setup` stays non-interactive on a clean re-run."
+        ),
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point. See module docstring for the exit-code contract."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.yes and args.check:
+        print(
+            "[setup_ghx] error: --yes and --check are mutually exclusive.",
+            file=sys.stderr,
+        )
+        return 2
+
+    if ghx_present():
+        # ASCII-only success line so PS 5.1 cp1252 stdout never corrupts
+        # the output. The leading tag mirrors `[setup_windows] ...` in
+        # scripts/setup_windows.ps1 so operators see one consistent
+        # provenance prefix across the setup surface.
+        print("[setup_ghx] ghx already on PATH -- skipping install.")
+        return 0
+
+    if args.check:
+        print(
+            "[setup_ghx] ghx not on PATH; recommended for speed -- "
+            "run `task setup` (without --check) to opt in. Consumer projects "
+            "only require gh. Refs #884."
+        )
+        return 0
+
+    consent: bool
+    if args.yes:
+        consent = True
+        print("[setup_ghx] --yes provided; skipping interactive consent prompt.")
+    else:
+        # Honour the documented opt-out env-var so non-interactive shells
+        # (CI hooks, dotfile bootstraps) can suppress the prompt without
+        # passing --check explicitly. This is purely additive -- the
+        # default still requires explicit consent.
+        if os.environ.get("DEFT_SETUP_GHX_SKIP", "").strip() in ("1", "true", "yes"):
+            print(
+                "[setup_ghx] DEFT_SETUP_GHX_SKIP set; skipping ghx install. "
+                "Refs #884."
+            )
+            return 0
+        consent = prompt_consent()
+
+    if not consent:
+        print(
+            "[setup_ghx] Skipping ghx install. ghx is recommended for speed "
+            "for maintainers and swarm runs; consumer projects only require gh "
+            "(see https://github.com/brunoborges/ghx, #884)."
+        )
+        return 0
+
+    host = detect_host()
+    try:
+        rc = install_ghx(host)
+    except RuntimeError as exc:
+        print(f"[setup_ghx] error: {exc}", file=sys.stderr)
+        return 1
+    if rc != 0:
+        print(
+            f"[setup_ghx] error: upstream installer exited {rc}. "
+            "See https://github.com/brunoborges/ghx#install for manual options.",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        "[setup_ghx] ghx installed. Open a fresh shell so the updated PATH "
+        "takes effect, then re-run `task setup` to verify."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/setup_windows.ps1

@@ -0,0 +1,220 @@
+# setup_windows.ps1 -- idempotent winget bootstrap for the deft Windows
+# maintainer toolchain (Go, Python 3.12+, uv, Task, GitHub CLI).
+#
+# Probes each tool via Get-Command first; only invokes `winget install` when
+# the tool is missing. After installs, dot-sources scripts/refresh-path.ps1 so
+# the running session sees the newly-installed binaries without requiring a
+# fresh shell.
+#
+# Usage:
+#   pwsh -ExecutionPolicy Bypass -File scripts\setup_windows.ps1
+#   # or, via the parent Taskfile alias:
+#   task setup:toolchain
+#
+# Tests: tests/scripts/test_setup_windows.ps1
+# Companion: scripts/refresh-path.ps1
+# Issue: #902
+#
+# ASCII-only by policy (AGENTS.md PowerShell rule). Do not introduce em
+# dashes, smart quotes, arrows, or other non-ASCII glyphs in this file.
+
+[CmdletBinding()]
+param(
+    # When set, the script only reports what it would do without invoking
+    # winget. Useful for dry-run validation in tests and CI.
+    [switch] $WhatIfOnly,
+
+    # Test seam: list of probe names to treat as missing regardless of the
+    # actual host PATH. Lets the regression suite exercise the
+    # "winget install" branch without mutating the host.
+    [string[]] $ForceMissing = @(),
+
+    # Test seam: scriptblock invoked instead of winget for each missing tool.
+    # The block is invoked with the canonical winget package id as its single
+    # argument. When unset, the script invokes `winget install` directly.
+    [scriptblock] $InstallOverride,
+
+    # Test seam: when set, skips the post-install dot-source of
+    # refresh-path.ps1. Tests use this to keep $env:PATH stable.
+    [switch] $SkipRefresh
+)
+
+# NOTE: $ErrorActionPreference is set INSIDE Invoke-DeftWindowsSetup so it
+# scopes to the function body and never leaks into a dot-source caller's
+# scope (e.g. the Pester Describe blocks that dot-source this file via
+# BeforeAll). See #909 cycle-3 P1 finding.
+
+# Capture $PSScriptRoot at script load time (before any function definitions)
+# so the refresh-path.ps1 lookup inside Invoke-DeftWindowsSetup remains
+# correct when the script is dot-sourced from a different directory. The
+# $script: scope qualifier ensures the value persists across the function-
+# definition / function-call boundary. See #909 cycle-3 P1 finding.
+$script:DeftSetupScriptRoot = $PSScriptRoot
+
+# Tool registry. Each entry maps a probe command (the binary name resolved
+# via Get-Command) to its canonical winget package id. The id list is the
+# acceptance criterion in #902 plus the GitHub.cli sibling.
+$DeftWindowsTools = @(
+    [pscustomobject]@{ Name = 'go';     Probe = 'go';     WingetId = 'GoLang.Go' },
+    [pscustomobject]@{ Name = 'python'; Probe = 'python'; WingetId = 'Python.Python.3.12' },
+    [pscustomobject]@{ Name = 'uv';     Probe = 'uv';     WingetId = 'astral-sh.uv' },
+    [pscustomobject]@{ Name = 'task';   Probe = 'task';   WingetId = 'Task.Task' },
+    [pscustomobject]@{ Name = 'gh';     Probe = 'gh';     WingetId = 'GitHub.cli' }
+)
+
+function Test-DeftWindowsAppsStub {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [object] $Command
+    )
+    # Windows App Installer ships %LOCALAPPDATA%\Microsoft\WindowsApps\<name>.exe
+    # stubs (notably python.exe) that redirect to the Microsoft Store rather
+    # than launching a real interpreter. Get-Command resolves these stubs, so
+    # a naive presence check causes `winget install` to be skipped silently.
+    # Treat any binary whose Source path is anchored under WindowsApps as a
+    # stub so the install branch fires on stock Windows 10/11 hosts.
+    if ($null -eq $Command) { return $false }
+    if (-not $Command.Source) { return $false }
+    return ($Command.Source -match '\\WindowsApps\\')
+}
+
+function Test-DeftToolPresent {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Probe,
+
+        [string[]] $ForceMissing = @()
+    )
+    if ($ForceMissing -contains $Probe) { return $false }
+    $cmd = Get-Command -Name $Probe -ErrorAction SilentlyContinue
+    if ($null -eq $cmd) { return $false }
+    if (Test-DeftWindowsAppsStub -Command $cmd) { return $false }
+    return $true
+}
+
+function Test-DeftWingetSuccess {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [int] $ExitCode
+    )
+    # 3010 = ERROR_SUCCESS_REBOOT_REQUIRED -- the install succeeded but a
+    # reboot is needed (Python's MSI, Go's installer, etc. propagate this
+    # via winget). Treating it as a failure causes the script to add the
+    # tool to $failed and exit 1 even though the binary is installed --
+    # which means a fresh-machine bootstrap visibly "fails" on first run.
+    # The downstream PATH refresh handles the session PATH; an actual
+    # reboot is only required for kernel-level changes that this toolchain
+    # does not produce. See #909 cycle-4 P1 finding.
+    return ($ExitCode -eq 0 -or $ExitCode -eq 3010)
+}
+
+function Invoke-DeftWingetInstall {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $WingetId
+    )
+    $wingetArgs = @(
+        'install',
+        '--id', $WingetId,
+        '-e',
+        '--silent',
+        '--accept-source-agreements',
+        '--accept-package-agreements'
+    )
+    & winget @wingetArgs
+    if (-not (Test-DeftWingetSuccess -ExitCode $LASTEXITCODE)) {
+        throw ("winget install --id {0} exited with code {1}" -f $WingetId, $LASTEXITCODE)
+    }
+}
+
+function Invoke-DeftWindowsSetup {
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [switch] $WhatIfOnly,
+        [string[]] $ForceMissing = @(),
+        [scriptblock] $InstallOverride,
+        [switch] $SkipRefresh
+    )
+
+    # Scope $ErrorActionPreference to the function body so it does not
+    # mutate the caller's scope when this file is dot-sourced. See #909.
+    $ErrorActionPreference = 'Stop'
+
+    $installed = New-Object System.Collections.ArrayList
+    $alreadyPresent = New-Object System.Collections.ArrayList
+    $failed = New-Object System.Collections.ArrayList
+
+    foreach ($tool in $DeftWindowsTools) {
+        $present = Test-DeftToolPresent -Probe $tool.Probe -ForceMissing $ForceMissing
+        if ($present) {
+            [void]$alreadyPresent.Add($tool.Name)
+            Write-Host ("[setup_windows] {0}: present (skip)" -f $tool.Name)
+            continue
+        }
+
+        Write-Host ("[setup_windows] {0}: missing -- installing {1}" -f $tool.Name, $tool.WingetId)
+        if ($WhatIfOnly) {
+            [void]$installed.Add($tool.Name)
+            continue
+        }
+
+        try {
+            if ($null -ne $InstallOverride) {
+                & $InstallOverride $tool.WingetId
+            } else {
+                Invoke-DeftWingetInstall -WingetId $tool.WingetId
+            }
+            [void]$installed.Add($tool.Name)
+        } catch {
+            Write-Warning ("[setup_windows] failed to install {0}: {1}" -f $tool.Name, $_)
+            [void]$failed.Add($tool.Name)
+        }
+    }
+
+    if (-not $SkipRefresh -and -not $WhatIfOnly -and $installed.Count -gt 0) {
+        # Use the script-scope variable captured at dot-source time. Bare
+        # $PSScriptRoot here would resolve to the caller's directory when
+        # this function is invoked from a dot-sourced context. See #909.
+        $refreshScript = Join-Path $script:DeftSetupScriptRoot 'refresh-path.ps1'
+        if (Test-Path -LiteralPath $refreshScript) {
+            . $refreshScript
+        } else {
+            Write-Warning ("[setup_windows] refresh-path.ps1 not found at {0}" -f $refreshScript)
+        }
+    }
+
+    $installedStr = if ($installed.Count -gt 0) { $installed -join ', ' } else { 'none' }
+    $presentStr = if ($alreadyPresent.Count -gt 0) { $alreadyPresent -join ', ' } else { 'none' }
+    Write-Host ("[setup_windows] Installed: {0}. Already present: {1}." -f $installedStr, $presentStr)
+    if ($failed.Count -gt 0) {
+        Write-Warning ("[setup_windows] Failed: {0}" -f ($failed -join ', '))
+    }
+
+    return [pscustomobject]@{
+        Installed      = @($installed)
+        AlreadyPresent = @($alreadyPresent)
+        Failed         = @($failed)
+    }
+}
+
+# Run the bootstrap unless the script was dot-sourced (the test suite dot-
+# sources to access the helper functions without triggering the main flow).
+if ($MyInvocation.InvocationName -ne '.') {
+    $result = Invoke-DeftWindowsSetup `
+        -WhatIfOnly:$WhatIfOnly `
+        -ForceMissing $ForceMissing `
+        -InstallOverride $InstallOverride `
+        -SkipRefresh:$SkipRefresh
+    if ($result.Failed.Count -gt 0) {
+        exit 1
+    }
+}