Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/actionlint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
59 changes: 59 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

# CI staging
go.sum.bkp
/tmp

# Windows
*.exe
Expand Down
30 changes: 19 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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]
Expand Down
8 changes: 8 additions & 0 deletions get-app/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
node_modules/
.wrangler/
.dev.vars
stackql
stackql.exe
stackql.zip
stackql.pkg
stackql-*-shell.sh
139 changes: 139 additions & 0 deletions get-app/README.md
Original file line number Diff line number Diff line change
@@ -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
```
Loading
Loading