stackql · general-kroll-4-life · Jun 25, 2026 · Jun 24, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
@@ -7,4 +7,5 @@ self-hosted-runner:
     - arm-ubuntu-22-04-runner-one
     - macos-14 # should not be necessary
     - macos-15 # should not be necessary
-    - macos-15-intel # should not be necessary
+    - macos-15-intel # should not be necessary
+    - windows-11-arm # GitHub-hosted arm64 Windows runner, newer than actionlint's built-in label list
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -20,6 +20,10 @@ on:
       - 'AGENTS.md'
       - 'CLAUDE.md'
       - 'server.json'
+      - 'glama.json'
+      - 'get-app/**'
+      - 'test-get-app.ps1'
+      - 'test-get-app.sh'
   pull_request:
     branches:
       - main
@@ -37,6 +41,10 @@ on:
       - 'AGENTS.md'
       - 'CLAUDE.md'
       - 'server.json'
+      - 'glama.json'
+      - 'get-app/**'
+      - 'test-get-app.ps1'
+      - 'test-get-app.sh'
 env:
   GOTESTCMD: "go test -timeout 1200s --tags \"sqlite_stackql\" -v ./..."
   TESTSCRIPT: "test/deprecated/python/main.py"
@@ -329,6 +337,57 @@ jobs:
         name: stackql_windows_amd64
         path: build/stackql.exe
 
+  winarmsmoke:
+    name: Windows arm64 Smoke (x64 emulation)
+    needs: winbuild
+    runs-on: windows-11-arm
+    timeout-minutes: ${{ vars.DEFAULT_SHORT_JOB_TIMEOUT_MIN == '' && 15 || vars.DEFAULT_SHORT_JOB_TIMEOUT_MIN }}
+    steps:
+
+    # We deliberately do NOT build here: there is no native windows/arm64 build
+    # (goreleaser only targets windows/amd64). This job downloads the amd64 .exe
+    # produced by winbuild and runs it on a native arm64 host, validating that it
+    # works under Windows 11's built-in x64 emulation - the basis for the
+    # "runs on Windows-on-ARM via emulation" claim in the install docs.
+    - name: Download Windows amd64 artifact
+      uses: actions/download-artifact@v4.1.2
+      with:
+        name: stackql_windows_amd64
+        path: build
+
+    - name: Confirm host is arm64 (binary under test is x64)
+      shell: pwsh
+      run: |
+        Write-Host "PROCESSOR_ARCHITECTURE = $env:PROCESSOR_ARCHITECTURE"
+        if ($env:PROCESSOR_ARCHITECTURE -notmatch 'ARM64') {
+          throw "expected an arm64 host so the x64 binary is emulated, got '$env:PROCESSOR_ARCHITECTURE'"
+        }
+
+    - name: Smoke test - version and exec under emulation
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = 'Stop'
+        $bin = ".\build\stackql.exe"
+
+        Write-Host "== stackql --version =="
+        & $bin --version
+        if ($LASTEXITCODE -ne 0) { throw "stackql --version failed (exit $LASTEXITCODE)" }
+
+        # 'exec' runs a query in batch mode (no TTY needed) and exercises the same
+        # cgo/sqlite engine the interactive shell uses, so it fully covers the
+        # "x64 binary runs under emulation" claim. The interactive shell is not
+        # smoke-tested here: it's a REPL that requires a TTY, so piping a query to
+        # it yields EOF + "goodbye" without ever executing the query.
+        # Native command output is an array of lines; Out-String collapses it so
+        # -match returns a scalar boolean.
+        Write-Host "== stackql exec ""select 'StackQL'"" =="
+        $execOut = (& $bin exec "select 'StackQL' as smoke" | Out-String)
+        if ($LASTEXITCODE -ne 0) { throw "stackql exec failed (exit $LASTEXITCODE)" }
+        Write-Host $execOut
+        if ($execOut -notmatch 'StackQL') { throw "exec did not return 'StackQL'" }
+
+        Write-Host "Windows arm64 (x64 emulation) smoke PASSED"
+
   linuxbuild:
     name: Linux Build
     runs-on: ubuntu-22.04

diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,6 @@
-
 # CI staging
 go.sum.bkp
+/tmp
 
 # Windows
 *.exe

diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@
 [forks]: https://img.shields.io/github/forks/stackql/stackql?style=flat-square "GitHub Forks"
 [contributors]: https://img.shields.io/github/contributors/stackql/stackql?style=flat-square "Contributors"
 [mcpregistrybadge]: https://img.shields.io/badge/MCP%20Registry-io.github.stackql%2Fstackql--mcp-blue?style=flat-square "MCP Registry"
+[mcpserver]: https://img.shields.io/npm/v/@stackql/mcp-server?style=flat-square&label=mcp%20server "MCP Server"
 <!-- github links -->
 [issues]: https://github.com/stackql/stackql/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D
 [features]: https://github.com/stackql/stackql/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D
@@ -38,40 +39,47 @@
 <!-- misc links -->
 [twitter]: https://twitter.com/stackql
 [mcpregistry]: https://registry.modelcontextprotocol.io/?search=stackql
+[npmjsmcpregistry]: https://www.npmjs.com/package/@stackql/mcp-server
 [mcpdocs]: https://stackql.io/docs
 
 <!-- language: lang-none -->
 <div align="center">
 
 [![logo]][homepage]  
+
 ![platforms]
 ![license]
 ![build]
 [![MCP Registry][mcpregistrybadge]][mcpregistry]
+[![MCP Server][mcpserver]][npmjsmcpregistry]
+![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release)
+![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads)
+![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql)
 ![stars]
-![forks]
-![contributors]
 
 </div>
 
-<div align="center">
+<!-- <div align="center"> -->
+
+<!-- ![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release) -->
+<!-- ![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads) -->
+<!-- ![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql) -->
+<!-- ![Chocolatey Downloads](https://img.shields.io/chocolatey/dt/stackql?label=chocolatey%20downloads) -->
 
+<!-- ![Docker Image Version](https://img.shields.io/docker/v/stackql/stackql?label=docker%20version) -->
+<!-- ![Chocolatey Version](https://img.shields.io/chocolatey/v/stackql) -->
+<!-- ![homebrew version](https://img.shields.io/homebrew/v/stackql?label=homebrew%20version) -->
 <!-- ![homebrew downloads](https://img.shields.io/homebrew/installs/dy/stackql?label=homebrew%20downloads) -->
-![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release)
-![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads)
-![Docker Image Version](https://img.shields.io/docker/v/stackql/stackql?label=docker%20version)
-![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql)
-![Chocolatey Downloads](https://img.shields.io/chocolatey/dt/stackql?label=chocolatey%20downloads)
-![Chocolatey Version](https://img.shields.io/chocolatey/v/stackql)
-![homebrew version](https://img.shields.io/homebrew/v/stackql?label=homebrew%20version)
 <!-- ![PyPI - Downloads](https://img.shields.io/pypi/dm/stackql-deploy?label=pypi%20downloads) -->
 
-</div>
+<!-- </div> -->
 <div align="center">
 
 ### Deploy, manage and query cloud resources and interact with APIs using SQL
+_The Universal Interface for the Agentic Era. Configuration-as-Data. Infrastructure-as-Context._
 <!-- <h3 align="center">SQL based XOps, observability and middleware framework</h3> -->
 
+
 <p align="center">
 
 [__Read the docs »__][docs]  

diff --git a/get-app/.gitignore b/get-app/.gitignore
@@ -0,0 +1,8 @@
+node_modules/
+.wrangler/
+.dev.vars
+stackql
+stackql.exe
+stackql.zip
+stackql.pkg
+stackql-*-shell.sh
diff --git a/get-app/README.md b/get-app/README.md
@@ -0,0 +1,139 @@
+# get-stackql.io
+
+Cloudflare Worker that backs `https://get-stackql.io`. It detects the calling
+platform and points the caller at the correct `stackql` release asset on GitHub.
+
+Behaviour:
+
+- `GET /` - reads the `User-Agent` and `302`-redirects to the matching release
+  asset (`stackql_windows_amd64.zip`, `stackql_darwin_multiarch.pkg`, or
+  `stackql_linux_amd64.zip`).
+- `GET /install` - universal installer. Detects the calling shell from the
+  User-Agent and serves the matching script: the POSIX `sh` installer for
+  curl/wget, or the PowerShell installer for `irm`/`iwr`. Use it as
+  `curl -fsSL https://get-stackql.io/install | sh` (Linux/macOS) or
+  `irm https://get-stackql.io/install | iex` (Windows).
+- `GET /install.sh` - always the POSIX `sh` installer. Runs `uname` client-side
+  to pick the right OS + arch asset and drops `./stackql` in the current dir.
+- `GET /install.ps1` - always the PowerShell installer. Downloads and expands the
+  Windows zip (`stackql.exe`) into the current directory.
+- `GET /install/<provider>` (also `GET /install.sh/<provider>`) - cloud shell /
+  web terminal helper installer. Serves an `sh` installer that drops `./stackql`
+  **and** the matching helper script (e.g. `stackql-aws-cloud-shell.sh`) into the
+  current directory, both executable. Providers: `aws`, `google`, `azure`,
+  `databricks`. Use it as `curl -fsSL https://get-stackql.io/install/aws | sh`.
+- Any other path - `301`-redirects to `https://stackql.io`.
+
+### Cloud shell helpers
+
+The helper scripts (`stackql-aws-cloud-shell.sh` etc.) used to be packaged into
+the Linux release zip. They are now embedded in the worker
+([`src/cloud-shell-scripts.ts`](src/cloud-shell-scripts.ts)) and delivered on
+demand via `/install/<provider>`. Each provider installer downloads the Linux
+binary, writes the helper alongside it, and makes both executable.
+
+These web terminals (AWS CloudShell, Google Cloud Shell, Azure Cloud Shell, the
+Databricks web terminal) are all Linux, so the helpers are served to Linux
+callers only. A macOS or Windows `User-Agent` is answered with a short
+`cloud shell helper scripts are supported for Linux downloads only` message
+instead of a script, and the generated installer re-checks `uname` at runtime as
+a backstop. Bare `curl`/`wget` (no OS in the UA, as in a cloud shell) are treated
+as Linux. Unknown providers get a message listing the supported ones.
+
+### Asset shapes
+
+stackql release assets are not uniform, so the installers do a little more than a
+plain download-and-extract:
+
+- Linux (`stackql_linux_amd64.zip`, `stackql_linux_arm64.zip`) and Windows
+  (`stackql_windows_amd64.zip`) ship as zip archives containing the
+  `stackql`/`stackql.exe` binary.
+- macOS ships only as a multi-arch `.pkg` installer
+  (`stackql_darwin_multiarch.pkg`). The `sh` installer extracts the universal
+  binary from the pkg payload (`pkgutil --expand-full`) so the `curl | sh` flow
+  still lands a `./stackql` in the current directory rather than running a
+  system-wide install. `brew install stackql` remains the recommended macOS path.
+
+### Wrong-shell guards
+
+The installers give friendly guidance instead of cryptic interpreter errors when
+run in the wrong shell:
+
+- Fetch `/install.sh` with PowerShell -> served a short PowerShell message
+  pointing at `irm .../install.ps1 | iex`.
+- Fetch `/install.ps1` with curl/wget -> served a short `sh` message pointing at
+  `curl -fsSL .../install.sh | sh`.
+- `install.sh` run in a POSIX shell on Windows (Git Bash/MSYS - `uname` reports
+  `MINGW*`/`MSYS*`/`CYGWIN*`) -> message pointing at the PowerShell command.
+- `install.ps1` run under PowerShell on macOS/Linux (`$PSVersionTable.Platform`
+  is `Unix`) -> message pointing at the `sh` command.
+- Unsupported CPU architectures get a "no prebuilt binary for your CPU" message
+  with a link to the releases page, not "unsupported".
+
+## Develop
+
+```sh
+npm install
+npm run dev        # wrangler dev - serves on http://localhost:8787
+```
+
+Test locally:
+
+```sh
+curl -A "curl/8.4.0" http://localhost:8787/install            # -> sh installer
+curl -A "WindowsPowerShell/5.1" http://localhost:8787/install  # -> PowerShell installer
+curl -A "WindowsPowerShell/5.1" http://localhost:8787/install.sh   # -> "use install.ps1" guide
+curl -A "curl/8.4.0" http://localhost:8787/install.ps1            # -> "use install.sh" guide
+curl -A "curl/8.4.0" http://localhost:8787/install/aws            # -> aws cloud shell installer
+curl -A "Mozilla/5.0 (Macintosh)" http://localhost:8787/install/aws  # -> "Linux downloads only"
+curl -sI -A "Mozilla/5.0 (Macintosh)" http://localhost:8787/   # -> 302 to macos pkg
+curl -sI -A "curl/8.4.0" http://localhost:8787/                # -> 302 to linux zip
+```
+
+## Smoke test
+
+The repo root carries client-side smoke tests that exercise every endpoint and
+shell guard against the live site, then run the real installer and check the
+downloaded binary:
+
+```sh
+sh ../test-get-app.sh            # macOS / Linux
+```
+
+```powershell
+..\test-get-app.ps1              # Windows
+```
+
+## Deploy
+
+This Worker is deployed manually (not via CI). One-time auth (uses your
+Cloudflare login):
+
+```sh
+npx wrangler login
+```
+
+Deploy:
+
+```sh
+npm run deploy     # wrangler deploy
+```
+
+`wrangler.toml` uses a `custom_domain` route for `get-stackql.io`. On the first
+deploy Wrangler creates and manages the proxied DNS record for the apex
+automatically - no manual DNS entry required. The `get-stackql.io` zone must
+already exist in the target Cloudflare account.
+
+If the apex already holds a record (e.g. an older deployment), the first deploy's
+custom-domain trigger fails with a `409 Conflict` on `.../domains/records` and the
+output reads `No targets deployed`. Clear the conflict via Workers & Pages ->
+get-stackql -> Settings -> Domains & Routes -> Add -> Custom Domain ->
+`get-stackql.io`, which prompts to override the existing record in a single step,
+then re-run `npm run deploy`. The output should report
+`get-stackql.io (custom domain)`.
+
+Tail live logs:
+
+```sh
+npm run tail
+```