@huynle/hub 0.8.3 → 0.8.5

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/config.ts

@@ -9,6 +9,7 @@ import { isLoopbackHost } from "../loopback"
 import { formatPattern, parsePattern } from "./agent/policy"
 import { APP_DIR, configBase, legacyPaths, migrateFirst, migrateStateDir, resolveHubStateDir, stateLegacyPaths } from "../migrate"
 import { updateSpeech, type StoredSpeech } from "./speech/settings"
+import { checkReleaseBase } from "./install/render"
 import { cspMode, type CspMode } from "./csp"
 
 export const GOOGLE_ISSUER = "https://accounts.google.com"
@@ -69,6 +70,11 @@ export interface CentralConfig {
   readonly launchCaps?: HubLaunches
   /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
   readonly webhooksAllowPrivate?: true
+  /**
+   * HUB_RELEASE_BASE: where /install.sh and /install.ps1 tell machines to download hubctl (default: this version's
+   * hub-releases GitHub release). https, or plain http on loopback or a private-network IP address.
+   */
+  readonly releaseBase?: string
   /** Cluster mode (design §9): set only when HUB_DATABASE_URL and HUB_VALKEY_URL (or hub.json cluster) are. */
   readonly cluster?: ClusterConfig
 }
@@ -473,6 +479,11 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
   if (!/^https?:\/\/[^\s/]+$/.test(publicURL)) {
     throw new Error(`HUB_PUBLIC_URL must be an http(s) origin without a path, got ${JSON.stringify(publicURL)}`)
   }
+  const rawReleaseBase = env.HUB_RELEASE_BASE?.trim()
+  const releaseBase = rawReleaseBase ? checkReleaseBase(rawReleaseBase) : undefined
+  if (rawReleaseBase && !releaseBase) {
+    throw new Error(`HUB_RELEASE_BASE must be an https URL (plain http only on loopback or a private-network IP address) without user info, query or quotes, got ${JSON.stringify(rawReleaseBase)}`)
+  }
   const auth = authConfig(env, file.auth)
   const cluster = clusterConfig(env, auth, file.cluster)
   return {
@@ -495,6 +506,7 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     agentsNever: [...(file.agents?.never ?? [])],
     ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
+    ...(releaseBase ? { releaseBase } : {}),
     ...(cluster ? { cluster } : {}),
   }
 }

package/src/central/http.ts

@@ -38,6 +38,7 @@ import type { Launch } from "./agent/launch-store"
 import { decisionStateQuery, MessageFeed } from "./agent/message-routes"
 import { hubDirectory } from "./agent/directory-routes"
 import type { Directory } from "./agent/directory"
+import { installResponse } from "./install/render"
 import { agentApi, agentRoutes, agentVerifiers, isAgentPath, wellKnown, type AgentRoute } from "./agent/routes"
 import { MCP_PATH, mcpHttp } from "./mcp-http"
 import { SessionTokens } from "./agent/session-tokens"
@@ -1509,6 +1510,15 @@ export function startCentral(options: CentralOptions): Central {
       if (method === "GET" && pathname === "/.well-known/hub") {
         return wellKnown({ publicURL, version: options.version ?? "0.0.0", auth: config.auth.mode === "oidc" ? { mode: "oidc", issuer: config.auth.issuer } : { mode: "pairing" } })
       }
+      // The machine setup one-liners (src/central/install/CONTRACT.md): public, no credentials in them.
+      if ((method === "GET" || method === "HEAD") && (pathname === "/install.sh" || pathname === "/install.ps1")) {
+        const res = installResponse(pathname === "/install.sh" ? "sh" : "ps1", url, {
+          publicURL,
+          version: options.version ?? "0.0.0",
+          ...(config.releaseBase ? { releaseBase: config.releaseBase } : {}),
+        })
+        return method === "HEAD" ? new Response(null, { status: res.status, headers: res.headers }) : res
+      }
       if (method === "GET" && pathname === "/login") return login(request, url)
       if (oidc && method === "GET" && pathname === "/auth/login") return await authLogin(url)
       if (oidc && method === "GET" && pathname === "/auth/callback") return await authCallback(request, url)

package/src/central/install/CONTRACT.md

@@ -0,0 +1,66 @@
+# Install scripts: shared contract (Phase 1)
+
+Design: `docs/plans/2026-11-05-machine-setup-installer-design.md`. Three workstreams build against this file; change
+it only through the integrator.
+
+## Routes (server)
+
+`GET /install.sh` and `GET /install.ps1`: public (no auth), dispatched in `src/central/http.ts` `handle()` before
+`/api/`, next to `/.well-known/hub`. Answer `200 text/plain; charset=utf-8`, `cache-control: no-store`,
+`x-content-type-options: nosniff`.
+
+Query (every key optional, each at most once; any other key → 400):
+
+| Key | Values | Default | install.ps1 (Phase 1) |
+|---|---|---|---|
+| `profile` | `session-only` · `launch-node` · `full-harness` | `session-only` | only `session-only`, else 400 |
+| `root` | workspace root for `launch-node`: 1–200 chars of `[A-Za-z0-9._/~-]`, starts with `/` or `~/`, no `..` segment, no `//` | `~/projects` when profile is `launch-node` | not allowed (400) |
+| `activate` | `0` · `1` | `0` | only `0` |
+
+`root` with another profile → 400. Errors are `400 text/plain` with a one-line reason (no script).
+
+Other answers: `503 text/plain` when this hub has no matching release (see `HUB_RELEASE_BASE`), `400` when the hub's
+public URL is plain `http` on a non-private host.
+
+## Template placeholders
+
+Templates are `src/central/install/install.sh` and `src/central/install/install.ps1`, imported as text. The server
+replaces every `{{NAME}}` below (each exactly as given; all values are pre-validated and contain none of
+`'` `"` `` ` `` `$` `\` newline, so templates put them inside single quotes). An unknown or leftover `{{…}}` is a
+server bug (tests check none remain).
+
+| Placeholder | Value |
+|---|---|
+| `{{HUB_URL}}` | the hub's public origin, no trailing slash (`https://hub.example.com`) |
+| `{{HUB_VERSION}}` | the hub version, e.g. `0.8.2` |
+| `{{RELEASE_BASE}}` | `https://github.com/huynle/hub-releases/releases/download/v<version>`, or `$HUB_RELEASE_BASE` (server env) when set |
+| `{{PROFILE}}` | the profile |
+| `{{WORKSPACE_ROOT}}` | the root, or empty |
+| `{{ACTIVATE}}` | `0` or `1` |
+| `{{INSECURE_HTTP}}` | `1` when `HUB_URL` is `http://` on loopback or a private-network IP, else `0` |
+
+## Script behaviour (scripts workstream)
+
+- All work in a `main` function called on the last line; a truncated download runs nothing.
+- `install.sh`: POSIX `sh`. Environment `HUB_INSTALL_RELEASE_BASE`, when set, overrides `{{RELEASE_BASE}}` (tests;
+  the local user controls it anyway). Downloads `hubctl-<target>`, `HUBCTL_SHA256SUMS`, `hubctl-manifest.json`.
+- `install.ps1`: runs under `irm … | iex`, so it must **never** call `exit` (that closes the user's window): every
+  failure is caught at the top, printed as one red `hub setup: …` line, and the function returns (the session stays
+  open). Windows PowerShell 5.1 and PowerShell 7 both, ASCII only. Phase 2 (`packages/cli/src/bootstrap/PHASE2-CONTRACT.md`):
+  x64 only (`PROCESSOR_ARCHITEW6432`, else `PROCESSOR_ARCHITECTURE`, must be `AMD64`); downloads
+  `hubctl-windows-x64.exe`, `HUBCTL_SHA256SUMS`, `hubctl-manifest.json` (`HUB_INSTALL_RELEASE_BASE` overrides, as in
+  install.sh; redirects followed, https stays https) into a private temp dir, checks the sha256, then runs install.sh's
+  hubctl sequence and exit-code handling with an empty stdin. After a successful apply it adds `<home>\.local\bin` to
+  the user PATH when missing (`HKCU\Environment` value read and written unexpanded, keeping its kind; a throwaway
+  `SetEnvironmentVariable` user variable is set and cleared to broadcast the change) and to the session's PATH.
+  `HUB_INSTALL_USER_PATH_FILE` (tests) stands in for the registry value.
+
+## Web (dialog workstream)
+
+The console builds commands from `me().publicURL` (fallback `location.origin`):
+
+- macOS / Linux: `curl -fsSL '<origin>/install.sh?<query>' | sh`
+- Windows: `irm '<origin>/install.ps1?<query>' | iex`
+
+`<query>` uses `URLSearchParams` with defaults left out (no query → bare path); `'` never appears (the allowlists
+exclude it).

package/src/central/install/install.ps1

@@ -0,0 +1,349 @@
+# Hub machine setup for Windows, served by the hub as GET /install.ps1 (see CONTRACT.md):
+#
+#   irm '<hub>/install.ps1' | iex
+#
+# The PowerShell twin of install.sh: downloads the hubctl release this hub pins (hubctl-windows-x64.exe), checks its
+# sha256, enrolls this machine with the hub (device code, approved in the console), then runs `hubctl setup preview`,
+# `setup apply` and `setup verify` for the session-only profile (the only one on Windows for now), and adds
+# %USERPROFILE%\.local\bin to the user PATH. Every hubctl run gets an empty stdin. Re-running it is safe: an enrolled
+# machine is not enrolled again, and apply converges.
+#
+# It runs inside the user's own PowerShell (`iex`), so it never calls exit: a failure prints one red "hub setup:"
+# line and returns. Everything is inside Invoke-HubSetup, called on the last line: a truncated download does not
+# parse, so nothing runs. Windows PowerShell 5.1 and PowerShell 7. ASCII only (5.1 reads a BOM-less script in the
+# ANSI code page).
+#
+# Environment, for tests (the local user controls it anyway): HUB_INSTALL_RELEASE_BASE overrides the release base,
+# as in install.sh; HUB_INSTALL_USER_PATH_FILE, when set, is a file that stands in for the user PATH in the
+# registry (HKCU\Environment), which is then never touched.
+function Invoke-HubSetup {
+  $HubUrl = '{{HUB_URL}}'
+  $HubVersion = '{{HUB_VERSION}}'
+  $ReleaseBase = '{{RELEASE_BASE}}'
+  $SetupProfile = '{{PROFILE}}'
+  $WorkspaceRoot = '{{WORKSPACE_ROOT}}'
+  $Activate = '{{ACTIVATE}}'
+  $InsecureHttp = '{{INSECURE_HTTP}}'
+
+  $ErrorActionPreference = 'Stop'
+  $onWindows = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
+
+  function Write-HubSay([string] $Message, [string] $Color = '') {
+    if ($Color) { Write-Host "hub setup: $Message" -ForegroundColor $Color }
+    else { Write-Host "hub setup: $Message" }
+  }
+
+  # The hubctl release asset for this machine, or a stop with the reason. A 32-bit PowerShell on 64-bit Windows sees x86
+  # in PROCESSOR_ARCHITECTURE and the machine's own architecture in PROCESSOR_ARCHITEW6432.
+  function Get-HubAsset {
+    $arch = $env:PROCESSOR_ARCHITEW6432
+    if (-not $arch) { $arch = $env:PROCESSOR_ARCHITECTURE }
+    if (-not $arch) { throw 'this does not look like Windows: on macOS and Linux use the install.sh command from the console' }
+    switch ($arch.ToUpperInvariant()) {
+      'AMD64' { return 'hubctl-windows-x64.exe' }
+      'ARM64' { throw 'windows-arm64 has no hubctl build yet: hubctl runs on 64-bit x86 (x64) Windows only for now' }
+      'X86' { throw 'this is 32-bit Windows, which hubctl does not support: it needs 64-bit x86 (x64) Windows' }
+      default { throw "this processor ($arch) is not supported: hubctl needs 64-bit x86 (x64) Windows" }
+    }
+  }
+
+  # The profile directory hubctl installs into (PHASE2-CONTRACT.md: HOME wins when set and absolute).
+  function Get-HubHome {
+    if ($env:HOME -and [IO.Path]::IsPathRooted($env:HOME)) { return $env:HOME }
+    if ($env:USERPROFILE) { return $env:USERPROFILE }
+    return [Environment]::GetFolderPath('UserProfile')
+  }
+
+  # A fresh directory only this user can read (icacls on Windows, chmod elsewhere).
+  function Initialize-HubTemp {
+    $base = $env:TEMP
+    if (-not $base) { $base = [IO.Path]::GetTempPath() }
+    $dir = Join-Path $base ('hub-setup-' + [Guid]::NewGuid().ToString('N'))
+    New-Item -ItemType Directory -Path $dir | Out-Null
+    if ($onWindows) {
+      $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+      & icacls.exe $dir /inheritance:r /grant:r "*$($sid):(OI)(CI)(F)" | Out-Null
+      if ($LASTEXITCODE -ne 0) { throw "icacls could not restrict $dir to you (code $LASTEXITCODE)" }
+    } else {
+      & chmod 700 $dir
+    }
+    return $dir
+  }
+
+  # One HttpClient that follows redirects itself (GitHub release downloads redirect to another host), so that an
+  # https download never continues over http.
+  function Open-HubClient {
+    try { Add-Type -AssemblyName System.Net.Http } catch { Write-Verbose 'System.Net.Http is already loaded' }
+    $handler = New-Object System.Net.Http.HttpClientHandler
+    $handler.AllowAutoRedirect = $false
+    $client = New-Object System.Net.Http.HttpClient($handler)
+    $client.Timeout = [TimeSpan]::FromMinutes(10)
+    return $client
+  }
+
+  function Save-HubFile($Client, [string] $Url, [string] $File) {
+    $uri = New-Object Uri($Url)
+    for ($hop = 0; $hop -le 5; $hop++) {
+      try {
+        $response = $Client.GetAsync($uri, [System.Net.Http.HttpCompletionOption]::ResponseHeadersRead).GetAwaiter().GetResult()
+      } catch {
+        throw "could not download $Url ($($_.Exception.GetBaseException().Message))"
+      }
+      try {
+        $code = [int]$response.StatusCode
+        if ($code -ge 300 -and $code -lt 400 -and $response.Headers.Location) {
+          $next = New-Object Uri($uri, $response.Headers.Location)
+          if ($uri.Scheme -eq 'https' -and $next.Scheme -ne 'https') {
+            throw "could not download $Url (it redirected to $($next.Scheme), and an https download follows redirects over https only)"
+          }
+          $uri = $next
+          continue
+        }
+        if (-not $response.IsSuccessStatusCode) { throw "could not download $Url (HTTP $code)" }
+        $out = [IO.File]::Create($File)
+        try { $response.Content.CopyToAsync($out).GetAwaiter().GetResult() } finally { $out.Dispose() }
+        return
+      } finally {
+        $response.Dispose()
+      }
+    }
+    throw "could not download $Url (too many redirects)"
+  }
+
+  # The lower-case sha256 for exactly $Name in a HUBCTL_SHA256SUMS file ("<sha256>  <file>", a leading * marks
+  # binary mode), or a stop.
+  function Get-HubExpectedSum([string] $File, [string] $Name) {
+    foreach ($line in [IO.File]::ReadAllLines($File)) {
+      $fields = @($line.Trim() -split '\s+')
+      if ($fields.Count -ne 2) { continue }
+      if ($fields[1].TrimStart('*') -ne $Name) { continue }
+      $sum = $fields[0].ToLowerInvariant()
+      if ($sum -notmatch '^[0-9a-f]{64}$') { throw "HUBCTL_SHA256SUMS has a malformed checksum for $Name; nothing was run" }
+      return $sum
+    }
+    throw "HUBCTL_SHA256SUMS has no checksum for $Name; nothing was run"
+  }
+
+  # One argument quoted for a Windows command line (CommandLineToArgvW rules; .NET parses them the same elsewhere).
+  function ConvertTo-HubArgument([string] $Value) {
+    if ($Value -ne '' -and $Value -notmatch '[\s"]') { return $Value }
+    $quoted = New-Object Text.StringBuilder
+    [void]$quoted.Append('"')
+    $slashes = 0
+    foreach ($c in $Value.ToCharArray()) {
+      if ($c -eq [char]'\') { $slashes++; continue }
+      if ($c -eq [char]'"') { [void]$quoted.Append('\' * (2 * $slashes + 1)) }
+      else { [void]$quoted.Append('\' * $slashes) }
+      [void]$quoted.Append($c)
+      $slashes = 0
+    }
+    [void]$quoted.Append('\' * (2 * $slashes)).Append('"')
+    return $quoted.ToString()
+  }
+
+  # Runs hubctl with an empty stdin and returns its exit code; with -Capture, an object with Code and Out (stdout;
+  # stderr is dropped, as install.sh drops `machine status` stderr). Otherwise its output goes to this console.
+  function Invoke-HubTool([string[]] $Arguments, [switch] $Capture) {
+    $start = New-Object System.Diagnostics.ProcessStartInfo
+    $start.FileName = $hubBin
+    $start.Arguments = (@($Arguments | ForEach-Object { ConvertTo-HubArgument $_ }) -join ' ')
+    $start.UseShellExecute = $false
+    $start.RedirectStandardInput = $true
+    if ($Capture) {
+      $start.RedirectStandardOutput = $true
+      $start.RedirectStandardError = $true
+      $start.StandardOutputEncoding = New-Object Text.UTF8Encoding($false)
+    }
+    $process = [Diagnostics.Process]::Start($start)
+    try {
+      $process.StandardInput.Close()
+      if ($Capture) {
+        $stdout = $process.StandardOutput.ReadToEndAsync()
+        $stderr = $process.StandardError.ReadToEndAsync()
+        $process.WaitForExit()
+        [void]$stderr.GetAwaiter().GetResult()
+        return New-Object PSObject -Property @{ Code = $process.ExitCode; Out = $stdout.GetAwaiter().GetResult() }
+      }
+      $process.WaitForExit()
+      return $process.ExitCode
+    } finally {
+      $process.Dispose()
+    }
+  }
+
+  function Test-HubSamePath([string] $Entry, [string] $Dir) {
+    $expanded = [Environment]::ExpandEnvironmentVariables($Entry.Trim()).TrimEnd('\', '/')
+    return $expanded -ieq $Dir.TrimEnd('\', '/')
+  }
+
+  function Test-HubPathHas([string] $List, [string] $Dir) {
+    foreach ($entry in ($List -split ';')) {
+      if ($entry.Trim() -and (Test-HubSamePath $entry $Dir)) { return $true }
+    }
+    return $false
+  }
+
+  # Adds $Dir to the user PATH (HKCU\Environment) when it is not there yet; $true when it was added. The value is
+  # read and written as stored, so %VARS% in it stay unexpanded (Environment.SetEnvironmentVariable would expand them
+  # and store a plain string); setting and clearing a throwaway user variable through SetEnvironmentVariable then
+  # tells Windows (and new terminals) that the environment changed.
+  function Add-HubUserPath([string] $Dir) {
+    $seam = $env:HUB_INSTALL_USER_PATH_FILE
+    if ($seam) {
+      $current = ''
+      if (Test-Path -LiteralPath $seam) { $current = [IO.File]::ReadAllText($seam) }
+    } elseif ($onWindows) {
+      $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+      if (-not $key) { $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment') }
+      $current = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+    } else {
+      return $false
+    }
+    if (Test-HubPathHas $current $Dir) {
+      if ($key) { $key.Dispose() }
+      return $false
+    }
+    $next = $current.TrimEnd(';')
+    if ($next) { $next = "$next;$Dir" } else { $next = $Dir }
+    if ($seam) {
+      [IO.File]::WriteAllText($seam, $next)
+      return $true
+    }
+    try {
+      $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
+      if ($null -ne $key.GetValue('Path')) { $kind = $key.GetValueKind('Path') }
+      if ($kind -ne [Microsoft.Win32.RegistryValueKind]::String) { $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString }
+      $key.SetValue('Path', $next, $kind)
+    } finally {
+      $key.Dispose()
+    }
+    [Environment]::SetEnvironmentVariable('HUB_SETUP_PATH_CHANGED', '1', 'User')
+    [Environment]::SetEnvironmentVariable('HUB_SETUP_PATH_CHANGED', $null, 'User')
+    return $true
+  }
+
+  $tmp = $null
+  try {
+    $HubUrl = $HubUrl.TrimEnd('/')
+    if ($SetupProfile -ne 'session-only' -or $Activate -ne '0' -or $WorkspaceRoot -ne '') {
+      throw "on Windows only 'OpenCode only' (session-only) is available for now; pick it in the console"
+    }
+    $release = $env:HUB_INSTALL_RELEASE_BASE
+    if (-not $release) { $release = $ReleaseBase }
+    $release = $release.TrimEnd('/')
+
+    Write-HubSay "setting up this machine for $HubUrl (hub $HubVersion, profile $SetupProfile)"
+    if ($InsecureHttp -eq '1') {
+      Write-HubSay "warning: $HubUrl is plain http: this machine's token travels unencrypted on your network" 'Yellow'
+    }
+    $asset = Get-HubAsset
+    [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+
+    $tmp = Initialize-HubTemp
+
+    # ---------- download and check hubctl ----------
+    $hubBin = Join-Path $tmp 'hubctl.exe'
+    $manifest = Join-Path $tmp 'hubctl-manifest.json'
+    $sums = Join-Path $tmp 'HUBCTL_SHA256SUMS'
+    Write-HubSay "downloading $asset from $release"
+    $client = Open-HubClient
+    try {
+      Save-HubFile $client "$release/HUBCTL_SHA256SUMS" $sums
+      Save-HubFile $client "$release/$asset" $hubBin
+      Save-HubFile $client "$release/hubctl-manifest.json" $manifest
+    } finally {
+      $client.Dispose()
+    }
+    $expected = Get-HubExpectedSum $sums $asset
+    $actual = (Get-FileHash -LiteralPath $hubBin -Algorithm SHA256).Hash.ToLowerInvariant()
+    if ($actual -ne $expected) { throw "the sha256 of $asset does not match HUBCTL_SHA256SUMS (got $actual); nothing was run" }
+    if (-not $onWindows) { & chmod 700 $hubBin }
+    Write-HubSay 'checksum ok (hubctl checks the release manifest signature itself)'
+
+    # ---------- enrollment ----------
+    # Skipped only when hubctl reports this exact hub; otherwise `machine enroll` decides (it is a no-op for the
+    # same hub and refuses another hub without --reenroll). A credential this hub revoked is replaced.
+    $enroll = $true
+    $reenroll = $false
+    $status = Invoke-HubTool @('machine', 'status', '--json') -Capture
+    $state = $null
+    $server = $null
+    try {
+      $data = (ConvertFrom-Json $status.Out).data
+      $state = [string]$data.state
+      $server = [string]$data.server
+    } catch {
+      Write-Verbose 'hubctl machine status printed no JSON'
+    }
+    if ($server -eq $HubUrl) {
+      if ($status.Code -eq 0 -and @('verified', 'configured', 'insecure') -contains $state) {
+        $enroll = $false
+        Write-HubSay "this machine is already enrolled with $HubUrl ($state); not enrolling again"
+      } elseif ($status.Code -eq 9 -and $state -eq 'revoked') {
+        $reenroll = $true
+        Write-HubSay "$HubUrl revoked this machine's credential; enrolling it again"
+      }
+    }
+    if ($enroll) {
+      $command = @('machine', 'enroll', '--server', $HubUrl)
+      if ($InsecureHttp -eq '1') { $command += '--allow-insecure-http' }
+      if ($reenroll) { $command += '--reenroll' }
+      Write-HubSay 'enrolling: approve the code below in the hub console'
+      $rc = Invoke-HubTool $command
+      switch ($rc) {
+        0 { break }
+        5 { throw 'the enrollment was denied on the hub; nothing was set up. Run the command again to start over' }
+        4 { throw 'the enrollment did not complete (expired, cancelled, or this machine is enrolled with another hub: see above); nothing was set up' }
+        default { throw "enrollment failed (hubctl exit $rc); nothing was set up" }
+      }
+    }
+
+    # ---------- preview and apply ----------
+    $preview = Join-Path $tmp 'preview.json'
+    $rc = Invoke-HubTool @('setup', 'preview', '--profile', $SetupProfile, '--enrollment', 'separate', '--manifest', $manifest, '--out', $preview)
+    if ($rc -ne 0) { throw "setup preview failed (hubctl exit $rc); nothing was changed" }
+    if (-not (Test-Path -LiteralPath $preview) -or (Get-Item -LiteralPath $preview).Length -eq 0) {
+      throw 'setup preview wrote no preview; nothing was changed'
+    }
+    # Manual edits (a config behind a link, a format hubctl cannot edit losslessly) are blockers, and apply refuses
+    # the whole plan while any remains (contracts section 3.12, exit 10). The preview above printed them.
+    $blockers = (ConvertFrom-Json ([IO.File]::ReadAllText($preview))).preview.blockers
+    if ($null -ne $blockers -and @($blockers).Count -gt 0) {
+      throw 'nothing was applied: make the edits listed above by hand (hubctl does not write those files), then run this command again'
+    }
+
+    $rc = Invoke-HubTool @('setup', 'apply', '--preview', $preview, '--manifest', $manifest)
+    switch ($rc) {
+      0 { break }
+      10 { throw 'setup apply needs edits by hand or found a conflict (see above); resolve them, then run this command again' }
+      default { throw "setup apply failed (hubctl exit $rc); see above" }
+    }
+
+    # ---------- PATH ----------
+    $userBin = Join-Path (Join-Path (Get-HubHome) '.local') 'bin'
+    if (Add-HubUserPath $userBin) {
+      Write-HubSay "added $userBin to your user PATH; open a new terminal to run hub and hubctl by name in other windows"
+    }
+    $sep = [IO.Path]::PathSeparator
+    $inSession = $false
+    foreach ($entry in ([string]$env:PATH -split [regex]::Escape($sep))) {
+      if ($entry -and (Test-HubSamePath $entry $userBin)) { $inSession = $true }
+    }
+    if (-not $inSession) { $env:PATH = ([string]$env:PATH).TrimEnd($sep) + $sep + $userBin }
+
+    # ---------- verify ----------
+    $rc = Invoke-HubTool @('setup', 'verify', '--profile', $SetupProfile)
+    switch ($rc) {
+      0 { Write-HubSay "done: this machine is set up for $HubUrl" 'Green' }
+      15 { Write-HubSay 'installed, not ready yet: finish the next steps above, then check with: hubctl setup verify' 'Yellow' }
+      default { throw "setup verify failed (hubctl exit $rc)" }
+    }
+  } catch {
+    Write-HubSay $_.Exception.Message 'Red'
+  } finally {
+    if ($tmp -and (Test-Path -LiteralPath $tmp)) {
+      try { Remove-Item -LiteralPath $tmp -Recurse -Force } catch { Write-Verbose "could not remove $tmp" }
+    }
+  }
+}
+Invoke-HubSetup