move cli to module (#379)

Author: thomasp85

.github/workflows/release-packages.yml

@@ -62,8 +62,8 @@ jobs:
         uses: ./.github/workflows/actions/sign-files
         with:
           paths: |
-            ./src/target/release/packager/*.exe
-            ./src/target/release/packager/*.msi
+            ./ggsql-cli/target/release/packager/*.exe
+            ./ggsql-cli/target/release/packager/*.msi
         env:
           # environment variables required to sign with signtool
           SM_HOST: ${{ secrets.SM_HOST }}
@@ -76,14 +76,14 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ggsql-windows-nsis
-          path: src/target/release/packager/*.exe
+          path: ggsql-cli/target/release/packager/*.exe
           retention-days: 30
 
       - name: Upload MSI installer
         uses: actions/upload-artifact@v4
         with:
           name: ggsql-windows-msi
-          path: src/target/release/packager/*.msi
+          path: ggsql-cli/target/release/packager/*.msi
           retention-days: 30
 
   build-macos-x86_64:
@@ -162,10 +162,10 @@ jobs:
             xargs -0 -I{} codesign --force --options runtime --timestamp --sign "$SIGN_ID" "{}"
           # Then sign the executables with hardened runtime + entitlements
           codesign --force --options runtime --timestamp \
-            --entitlements src/entitlements.plist \
+            --entitlements entitlements.plist \
             --sign "$SIGN_ID" target/release/ggsql
           codesign --force --options runtime --timestamp \
-            --entitlements src/entitlements.plist \
+            --entitlements entitlements.plist \
             --sign "$SIGN_ID" target/release/ggsql-jupyter
 
       - name: Build and notarize PKG installer (x86_64)
@@ -285,10 +285,10 @@ jobs:
             xargs -0 -I{} codesign --force --options runtime --timestamp --sign "$SIGN_ID" "{}"
           # Then sign the executables with hardened runtime + entitlements
           codesign --force --options runtime --timestamp \
-            --entitlements src/entitlements.plist \
+            --entitlements entitlements.plist \
             --sign "$SIGN_ID" target/release/ggsql
           codesign --force --options runtime --timestamp \
-            --entitlements src/entitlements.plist \
+            --entitlements entitlements.plist \
             --sign "$SIGN_ID" target/release/ggsql-jupyter
 
       - name: Build and notarize PKG installer (aarch64)
@@ -377,7 +377,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ggsql-linux-deb-x86_64
-          path: src/target/release/packager/*.deb
+          path: ggsql-cli/target/release/packager/*.deb
           retention-days: 30
 
   build-linux-aarch64:
@@ -428,7 +428,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ggsql-linux-deb-aarch64
-          path: src/target/release/packager/*.deb
+          path: ggsql-cli/target/release/packager/*.deb
           retention-days: 30
 
   build-cargo:
@@ -485,6 +485,11 @@ jobs:
         env:
           CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
 
+      - name: Publish ggsql-cli
+        run: cargo publish --package ggsql-cli
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+
   build-wasm:
     name: Build Wasm Package (wasm32)
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -25,6 +25,7 @@ shapes (#368)
 before registering them back to the backend. We now keep the data purely on the
 backend until the layer query as was always intended (#363)
 - Simplified internal approach to DataFrame with DuckDB reader (#365)
+- Moved the CLI to its own module rather than be part of the main crate (#379)
 - Restructured CLAUDE.md to better deal with the rising complexity of the project (#382)
 
 ### Removed

CLAUDE.md

@@ -21,14 +21,15 @@ The user-facing site is at <https://ggsql.org>. The README at [`README.md`](READ
 
 | Folder | Role | Type | Per-folder CLAUDE.md |
 | --- | --- | --- | --- |
-| [`src/`](src/) | Core Rust library + `ggsql` CLI | Cargo workspace member | [`src/CLAUDE.md`](src/CLAUDE.md) |
+| [`src/`](src/) | Core Rust library (crate `ggsql`) | Cargo workspace member | [`src/CLAUDE.md`](src/CLAUDE.md) |
+| [`ggsql-cli/`](ggsql-cli/) | `ggsql` command-line binary | Cargo workspace member | [`ggsql-cli/CLAUDE.md`](ggsql-cli/CLAUDE.md) |
 | [`tree-sitter-ggsql/`](tree-sitter-ggsql/) | Tree-sitter grammar + multi-language bindings | Cargo workspace member (also npm + PyPI) | [`tree-sitter-ggsql/CLAUDE.md`](tree-sitter-ggsql/CLAUDE.md) |
 | [`ggsql-jupyter/`](ggsql-jupyter/) | Jupyter kernel | Cargo workspace member (also PyPI via maturin) | [`ggsql-jupyter/CLAUDE.md`](ggsql-jupyter/CLAUDE.md) |
 | [`ggsql-wasm/`](ggsql-wasm/) | WebAssembly bindings + browser playground | Cargo workspace member | [`ggsql-wasm/CLAUDE.md`](ggsql-wasm/CLAUDE.md) |
 | [`ggsql-vscode/`](ggsql-vscode/) | VS Code / Positron extension | Standalone TypeScript / npm | [`ggsql-vscode/CLAUDE.md`](ggsql-vscode/CLAUDE.md) |
 | [`doc/`](doc/) | Quarto documentation site (ggsql.org) | Quarto project | [`doc/CLAUDE.md`](doc/CLAUDE.md) |
 
-The Cargo workspace (`/Cargo.toml`) has four members: `tree-sitter-ggsql`, `src`, `ggsql-jupyter`, `ggsql-wasm`. Default workspace members exclude `ggsql-wasm` (it needs the wasm32 target and is built separately).
+The Cargo workspace (`/Cargo.toml`) has five members: `tree-sitter-ggsql`, `src`, `ggsql-cli`, `ggsql-jupyter`, `ggsql-wasm`. Default workspace members exclude `ggsql-wasm` (it needs the wasm32 target and is built separately).
 
 ## High-level pipeline
 
@@ -48,13 +49,16 @@ For details — module layout, traits, where extension points live — see [`src
 ## Building
 
 ```sh
-# Rust workspace (default members: tree-sitter-ggsql, src, ggsql-jupyter)
+# Rust workspace (default members: tree-sitter-ggsql, src, ggsql-cli, ggsql-jupyter)
 cargo build --workspace
 cargo build --release --workspace
 
-# Just the CLI / library
+# Just the library
 cargo build --package ggsql
 
+# Just the CLI binary
+cargo build --package ggsql-cli
+
 # Wasm build (separate, not in default workspace members)
 cd ggsql-wasm && ./build-wasm.sh
 
@@ -89,6 +93,7 @@ Per-folder CLAUDE.md files cover component-specific test guidance.
 ## Where to ask which question
 
 - *What does clause/layer/scale X do?* → [`doc/syntax/`](doc/syntax/).
+- *How does the `ggsql` CLI work? Where do its subcommands live?* → [`ggsql-cli/CLAUDE.md`](ggsql-cli/CLAUDE.md).
 - *How does the parser work? How is a `Plot` built?* → [`src/CLAUDE.md`](src/CLAUDE.md), then `src/parser/`.
 - *How do I add a new geom / scale type / coord?* → [`src/plot/CLAUDE.md`](src/plot/CLAUDE.md).
 - *How does Vega-Lite output get assembled?* → [`src/writer/vegalite/CLAUDE.md`](src/writer/vegalite/CLAUDE.md).

Cargo.lock

@@ -2,12 +2,14 @@
 members = [
     "tree-sitter-ggsql",
     "src",
+    "ggsql-cli",
     "ggsql-jupyter",
     "ggsql-wasm"
 ]
 default-members = [
     "tree-sitter-ggsql",
     "src",
+    "ggsql-cli",
     "ggsql-jupyter"
 ]
 resolver = "2"

Cargo.toml

@@ -1,52 +1,69 @@
 # Building Cross-Platform Installers
 
-ggsql uses [cargo-packager](https://github.com/crabnebula-dev/cargo-packager) to create native installers for Windows, macOS, and Linux.
+ggsql ships native installers for Windows, macOS, and Linux. Windows (NSIS / MSI) and Linux (Deb) installers are built via [cargo-packager](https://github.com/crabnebula-dev/cargo-packager); macOS installers are built directly with Apple's `pkgbuild`, then code-signed and notarized.
 
 ## Quick Start
 
 ### Prerequisites
 
-1. **Install cargo-packager**:
+1. **For Windows / Linux installers — install cargo-packager**:
 
    ```bash
    cargo install cargo-packager --locked
    ```
 
 2. **Platform-specific requirements**:
    - **Windows**: No additional requirements (uses built-in NSIS, optionally WiX if installed)
-   - **macOS**: Xcode Command Line Tools
+   - **macOS**: Xcode Command Line Tools, plus [`dylibbundler`](https://github.com/auriamg/macdylibbundler) (`brew install dylibbundler`) for bundling Arrow / DuckDB dynamic libraries
    - **Linux**: `sudo apt-get install libgtk-3-dev libwebkit2gtk-4.0-dev libappindicator3-dev librsvg2-dev patchelf`
 
 ### Build Installers Locally
 
-From the `src/` directory:
-
 ```bash
 # Windows
-cd src
+cd ggsql-cli
 cargo packager --release --formats nsis    # Creates .exe installer (NSIS)
 cargo packager --release --formats wix     # Creates .msi installer (WiX)
 
-# macOS
-cd src
-cargo packager --release --formats dmg     # Creates .dmg disk image
-
 # Linux
-cd src
+cd ggsql-cli
 cargo packager --release --formats deb     # Creates .deb package (Debian/Ubuntu)
 ```
 
-Output location: `src/target/release/packager/`
+Output for cargo-packager: `ggsql-cli/target/release/packager/`.
+
+**macOS** uses a separate `pkgbuild` flow (matches what CI ships). From the workspace root:
+
+```bash
+# Build the binaries
+cargo build --release --bin ggsql --bin ggsql-jupyter
+
+# Bundle dylibs alongside the binaries
+dylibbundler -cd -of -b -x target/release/ggsql         -d ./libs/ -p "@executable_path/../lib/ggsql/"
+dylibbundler -cd -of -b -x target/release/ggsql-jupyter -d ./libs/ -p "@executable_path/../lib/ggsql/"
+
+# Stage payload and build an unsigned .pkg
+mkdir -p pkg-payload/usr/local/bin pkg-payload/usr/local/lib/ggsql
+cp target/release/ggsql target/release/ggsql-jupyter pkg-payload/usr/local/bin/
+cp -R ./libs/. pkg-payload/usr/local/lib/ggsql/
+pkgbuild \
+  --root ./pkg-payload \
+  --install-location / \
+  --identifier co.posit.ggsql \
+  --version 0.0.0-dev \
+  ggsql-dev.pkg
+```
+
+CI additionally codesigns the binaries with `entitlements.plist` (Developer ID Application), signs the `.pkg` (Developer ID Installer), and notarizes via `xcrun notarytool` — see [`.github/workflows/release-packages.yml`](.github/workflows/release-packages.yml). Local builds without those creds produce an unsigned `.pkg` that's fine for testing but will be Gatekeeper-blocked on other machines.
 
 ## Available Formats
 
-| Platform    | Format     | Command          | Output                             |
-| ----------- | ---------- | ---------------- | ---------------------------------- |
-| **Windows** | NSIS       | `--formats nsis` | `ggsql_0.1.0_x64-setup.exe` (12MB) |
-| **Windows** | MSI        | `--formats wix`  | `ggsql_0.1.0_x64_en-US.msi` (15MB) |
-| **macOS**   | DMG        | `--formats dmg`  | `ggsql_0.1.0_x64.dmg`              |
-| **macOS**   | App Bundle | `--formats app`  | `ggsql.app`                        |
-| **Linux**   | Debian     | `--formats deb`  | `ggsql_0.1.0_amd64.deb`            |
+| Platform    | Format | Tool             | Output                          |
+| ----------- | ------ | ---------------- | ------------------------------- |
+| **Windows** | NSIS   | `cargo packager --formats nsis` | `ggsql_0.1.0_x64-setup.exe`     |
+| **Windows** | MSI    | `cargo packager --formats wix`  | `ggsql_0.1.0_x64_en-US.msi`     |
+| **macOS**   | PKG    | `pkgbuild` (see above)          | `ggsql_0.1.0_x86_64.pkg`, `ggsql_0.1.0_aarch64.pkg` |
+| **Linux**   | Debian | `cargo packager --formats deb`  | `ggsql_0.1.0_amd64.deb`         |
 
 ## What Gets Packaged
 
@@ -57,18 +74,19 @@ The installers include:
 
 ## Configuration
 
-Installer configuration is in `src/Cargo.toml` under `[package.metadata.packager]`:
+Windows / Linux installer configuration is in `ggsql-cli/Cargo.toml` under `[package.metadata.packager]` (the macOS `.pkg` build is driven entirely by the `pkgbuild` invocation in the workflow, not by this metadata):
 
 ```toml
 [package.metadata.packager]
 product-name = "ggsql"
 identifier = "com.ggsql.app"
 category = "DeveloperTool"
 publisher = "ggsql Team"
-icons = ["../doc/assets/icon.svg", "../doc/assets/logo.png"]
+icons = ["../doc/assets/logo.png"]
 license-file = "../LICENSE.md"
 binaries = [
   { path = "ggsql", main = true },
+  { path = "ggsql-jupyter", main = false },
 ]
 ```
 
@@ -81,9 +99,9 @@ git tag v0.1.0
 git push origin v0.1.0
 ```
 
-The workflow (`.github/workflows/release-installers.yml`) will:
+The workflow (`.github/workflows/release-packages.yml`) will:
 
-1. **Build installers** for Windows (NSIS + MSI), macOS (DMG), and Linux (Deb)
+1. **Build installers** for Windows (NSIS + MSI), macOS (PKG, x86_64 + aarch64, signed and notarized), and Linux (Deb, x86_64 + aarch64)
 2. **Create a GitHub Release** with all installers attached
 3. **Generate release notes** automatically
 
@@ -106,11 +124,11 @@ You can also trigger builds manually from the Actions tab.
 
 ### macOS
 
-**DMG Installer**
+**PKG Installer**
 
-- Open `ggsql_0.1.0_x64.dmg`
-- Drag `ggsql.app` to Applications folder
-- Or copy binaries directly to `/usr/local/bin`
+- Double-click `ggsql_0.1.0_x86_64.pkg` (Intel) or `ggsql_0.1.0_aarch64.pkg` (Apple Silicon)
+- Installs `ggsql` and `ggsql-jupyter` into `/usr/local/bin/` and bundled dylibs into `/usr/local/lib/ggsql<version>/`
+- CLI command-line install: `sudo installer -pkg ggsql_0.1.0_aarch64.pkg -target /`
 
 ### Linux
 
@@ -141,11 +159,15 @@ ggsql --version
 
 ```bash
 # Install
-hdiutil attach ggsql_0.1.0_x64.dmg
-cp -r /Volumes/ggsql/ggsql.app /Applications/
+sudo installer -pkg ggsql_0.1.0_aarch64.pkg -target /
 
 # Verify
-/Applications/ggsql.app/Contents/MacOS/ggsql --version
+ggsql --version
+ggsql-jupyter --version
+
+# Uninstall
+sudo rm /usr/local/bin/ggsql /usr/local/bin/ggsql-jupyter
+sudo rm -rf /usr/local/lib/ggsql*
 ```
 
 ### Linux
@@ -165,14 +187,16 @@ sudo apt-get remove ggsql
 
 This happens with unsigned installers. Click "More info" → "Run anyway". For production, sign the installer with a code signing certificate.
 
-### macOS: "ggsql.app is damaged"
+### macOS: ".pkg can't be opened" / "unidentified developer"
 
-This happens with unsigned apps. Run:
+Locally-built `.pkg` files are unsigned and Gatekeeper will block double-clicking them. Either install from the command line:
 
 ```bash
-xattr -cr /Applications/ggsql.app
+sudo installer -pkg ggsql-dev.pkg -target /
 ```
 
+…or right-click → Open to bypass Gatekeeper for that file. Official releases from GitHub are signed with the Developer ID Installer certificate and notarized, so they install without warnings.
+
 ### Linux: Missing dependencies
 
 If the Deb/RPM package fails to install, ensure you have the required system libraries:
@@ -191,7 +215,9 @@ Build for different architectures:
 ```bash
 # macOS: Build for Apple Silicon
 rustup target add aarch64-apple-darwin
-cargo packager --release --target aarch64-apple-darwin --formats dmg
+cargo build --release --target aarch64-apple-darwin --bin ggsql --bin ggsql-jupyter
+# Then run the dylibbundler + pkgbuild flow shown above against
+# target/aarch64-apple-darwin/release/ instead of target/release/.
 
 # Linux: Build for ARM64
 rustup target add aarch64-unknown-linux-gnu

INSTALLERS.md

@@ -88,7 +88,7 @@ uv tool install ggsql-jupyter
 ggsql-jupyter --install
 
 # CLI (crates.io)
-cargo install ggsql
+cargo install ggsql-cli
 ```
 :::
 :::