Linux Hub skeleton, substratalctl, and the versioned help center

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --quiet --package xtask --"

.github/workflows/api-spec-sync.yml

@@ -0,0 +1,89 @@
+# Keeps the vendored Platform API spec (vendor/openapi.yaml) current with
+# the API repo. (The help center's API reference is rebuilt from the live
+# spec by the specs repo itself.)
+#
+# Runs every 6 hours, on demand, and on a `repository_dispatch` of type
+# `api-spec-updated`. If openapi.yaml changed, it diffs old vs new with
+# oasdiff and opens (or updates) a pull request with the changelog,
+# labelled `breaking-change` when oasdiff finds one, so the app code gets
+# reviewed against the change.
+name: API spec sync
+
+on:
+  schedule:
+    - cron: "23 */6 * * *"
+  workflow_dispatch:
+  repository_dispatch:
+    types: [api-spec-updated]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: api-spec-sync
+  cancel-in-progress: false
+
+env:
+  SPEC_URL: https://raw.githubusercontent.com/CompositeCode/substratalapps.com/main/docs/openapi.yaml
+  OASDIFF_VERSION: 1.34.1
+
+jobs:
+  sync:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Fetch the API's current spec
+        id: fetch
+        run: |
+          curl -fsSL "$SPEC_URL" -o _new.yaml
+          if cmp -s vendor/openapi.yaml _new.yaml; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "openapi.yaml unchanged."
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "version=$(python3 -c 'import yaml;print(yaml.safe_load(open("_new.yaml"))["info"]["version"])')" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Diff with oasdiff
+        if: steps.fetch.outputs.changed == 'true'
+        id: diff
+        run: |
+          curl -fsSL "https://github.com/oasdiff/oasdiff/releases/download/v${OASDIFF_VERSION}/oasdiff_${OASDIFF_VERSION}_linux_amd64.tar.gz" | tar -xz oasdiff
+          ./oasdiff changelog vendor/openapi.yaml _new.yaml --format markdown > _changelog.md || true
+          if ./oasdiff breaking vendor/openapi.yaml _new.yaml --fail-on ERR > _breaking.txt; then
+            echo "breaking=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "breaking=true" >> "$GITHUB_OUTPUT"
+          fi
+          cat _changelog.md
+
+      - name: Update the vendored spec
+        if: steps.fetch.outputs.changed == 'true'
+        id: notes
+        run: |
+          mv _new.yaml vendor/openapi.yaml
+          { echo 'changelog<<EOF_CHANGELOG'; cat _changelog.md; echo 'EOF_CHANGELOG'; } >> "$GITHUB_OUTPUT"
+          rm -f oasdiff _changelog.md _breaking.txt
+
+      - uses: peter-evans/create-pull-request@v8
+        if: steps.fetch.outputs.changed == 'true'
+        with:
+          # A PAT (SYNC_TOKEN) lets the PR trigger CI; GITHUB_TOKEN PRs don't.
+          token: ${{ secrets.SYNC_TOKEN || github.token }}
+          branch: automation/api-spec-sync
+          delete-branch: true
+          commit-message: "Sync Platform API spec to ${{ steps.fetch.outputs.version }}"
+          title: "Sync Platform API spec to ${{ steps.fetch.outputs.version }}"
+          labels: |
+            api-spec
+            ${{ steps.diff.outputs.breaking == 'true' && 'breaking-change' || '' }}
+          body: |
+            The Platform API's `openapi.yaml` changed upstream. This updates `vendor/openapi.yaml`.
+
+            Breaking changes found by oasdiff: **${{ steps.diff.outputs.breaking }}**
+
+            ${{ steps.notes.outputs.changelog }}
+
+            Before merging, check the app against the change: hand-written models in `crates/substratal-core/src/models.rs`, and whether `Substratal-Version` (`crates/substratal-core/src/version.rs`) needs to move.

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+# Build, lint and test the app; check that spec-derived files and the
+# Linux help pages match their sources.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust:
+    name: Build and test (Ubuntu 24.04, GTK 4.14, libadwaita 1.5)
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install GTK, libadwaita and Blueprint
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libgtk-4-dev libadwaita-1-dev blueprint-compiler libdbus-1-dev \
+            desktop-file-utils appstream
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all --check
+      - run: cargo clippy --workspace --all-targets -- -D warnings
+      - run: cargo test --workspace
+      - name: Desktop and AppStream files are valid
+        run: |
+          desktop-file-validate data/com.substratalapps.Hub.desktop
+          appstreamcli validate --no-net data/com.substratalapps.Hub.metainfo.xml
+
+  specs:
+    name: Spec-derived files match the specs package
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: CompositeCode/substratalapps-applications-specs
+          path: _specs
+      - name: Check (warns only; the Specs sync workflow opens the update PR)
+        run: python3 scripts/sync-specs.py --specs _specs --check || echo "::warning::Specs package has changed since the last sync; see the Specs sync workflow."
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Linux help pages generate (warns when the help center needs an update)
+        run: |
+          if [ -d _specs/help/guides ]; then
+            cargo xtask gen-help --out _specs/help --check || echo "::warning::The Linux pages in the help center differ from this code; the Docs dispatch workflow updates them after merge."
+          fi
+

.github/workflows/docs-dispatch.yml

@@ -0,0 +1,79 @@
+# Keeps the Linux app's pages in the Hub help center current.
+#
+# The help center lives in the specs repo
+# (CompositeCode/substratalapps-applications-specs, help/) and is the one
+# documentation site for every Hub app. On every push to main that changes
+# the app, this:
+#   1. regenerates the pages that come from this app's code
+#      (`cargo xtask gen-help`: Linux keyboard shortcuts, substratalctl),
+#   2. opens or updates a pull request in the specs repo when they changed,
+#   3. sends `app-docs-updated` so the help center rebuilds.
+#
+# Needs the secret SPECS_DOCS_TOKEN: a fine-grained token with Contents and
+# Pull requests read/write on the specs repo (see help/README.md there).
+# Without it, the run regenerates and reports, and skips steps 2 and 3.
+name: Docs dispatch
+
+on:
+  push:
+    branches: [main]
+    paths: ["crates/**", ".github/workflows/docs-dispatch.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-dispatch
+  cancel-in-progress: false
+
+env:
+  SPECS_REPO: CompositeCode/substratalapps-applications-specs
+  HAS_TOKEN: ${{ secrets.SPECS_DOCS_TOKEN != '' }}
+
+jobs:
+  help:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check out the help center
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ env.SPECS_REPO }}
+          path: _specs
+          token: ${{ secrets.SPECS_DOCS_TOKEN || github.token }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Regenerate the Linux help pages
+        id: gen
+        run: |
+          if [ ! -d _specs/help/guides ]; then
+            echo "::notice::The specs repo's default branch has no help/ yet; nothing to update."
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          cargo xtask gen-help --out _specs/help
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+          git -C _specs status --short
+      - name: Open a pull request in the specs repo
+        if: steps.gen.outputs.ready == 'true' && env.HAS_TOKEN == 'true'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.SPECS_DOCS_TOKEN }}
+          path: _specs
+          branch: automation/linux-help
+          delete-branch: true
+          commit-message: "Update the Linux help pages from substratalapps-linux@${{ github.sha }}"
+          title: "Update the Linux help pages"
+          body: |
+            Regenerated by `cargo xtask gen-help` in CompositeCode/substratalapps-linux at ${{ github.sha }}: the Linux keyboard shortcuts and the `substratalctl` reference.
+      - name: Tell the help center to rebuild
+        if: env.HAS_TOKEN == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.SPECS_DOCS_TOKEN }}
+        run: |
+          gh api "repos/$SPECS_REPO/dispatches" -f event_type=app-docs-updated \
+            -F 'client_payload[app]=linux' -F "client_payload[sha]=$GITHUB_SHA"
+      - name: No token
+        if: env.HAS_TOKEN != 'true'
+        run: echo "::warning::SPECS_DOCS_TOKEN isn't set, so no PR or dispatch was sent to $SPECS_REPO."

.github/workflows/flatpak.yml

@@ -0,0 +1,37 @@
+# Builds the Flatpak bundle (GNOME 50 runtime) for x86_64 and aarch64.
+# Download it from the run's artifacts and install with
+#   flatpak install --user substratal-hub.flatpak
+name: Flatpak
+
+on:
+  push:
+    branches: [main]
+    paths: ["crates/**", "data/**", "build-aux/flatpak/**", "Cargo.lock"]
+  pull_request:
+    paths: ["build-aux/flatpak/**", "data/**", "Cargo.lock", ".github/workflows/flatpak.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  flatpak:
+    strategy:
+      matrix:
+        include:
+          - arch: x86_64
+            runner: ubuntu-24.04
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    container:
+      image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-50
+      options: --privileged
+    steps:
+      - uses: actions/checkout@v7
+      - uses: flatpak/flatpak-github-actions/flatpak-builder@v6
+        with:
+          bundle: substratal-hub-${{ matrix.arch }}.flatpak
+          manifest-path: build-aux/flatpak/com.substratalapps.Hub.json
+          arch: ${{ matrix.arch }}
+          cache-key: flatpak-builder-${{ github.sha }}

.github/workflows/specs-sync.yml

@@ -0,0 +1,47 @@
+# Keeps the spec-derived files (screen registry, themes, icons, status
+# semantics) current with the client specs package. Daily and on demand; opens a pull request when anything
+# changed.
+name: Specs sync
+
+on:
+  schedule:
+    - cron: "41 5 * * *"
+  workflow_dispatch:
+  repository_dispatch:
+    types: [client-specs-updated]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: specs-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: CompositeCode/substratalapps-applications-specs
+          path: _specs
+      - name: Sync spec-derived files
+        id: sync
+        run: |
+          python3 scripts/sync-specs.py --specs _specs
+          echo "commit=$(git -C _specs rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+          rm -rf _specs
+      - uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.SYNC_TOKEN || github.token }}
+          branch: automation/specs-sync
+          delete-branch: true
+          commit-message: "Sync client specs (${{ steps.sync.outputs.commit }})"
+          title: "Sync client specs (${{ steps.sync.outputs.commit }})"
+          labels: specs
+          body: |
+            The client specs package changed upstream (`CompositeCode/substratalapps-applications-specs@${{ steps.sync.outputs.commit }}`). This regenerates `data/spec/` and the bundled themes and icons.
+
+            New or changed screens appear in the app as spec scaffolds automatically; check `cargo test` (route and navigation tests) and any hand-built screens they affect.

.gitignore

@@ -0,0 +1,8 @@
+/target
+/_site
+/_specs
+/_archive
+.DS_Store
+/build-aux/flatpak/.flatpak-builder
+/build-aux/flatpak/build-dir
+/_screens