ground_control-api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4151207335fd8c45c84426ef8743b3291149dc545d093537c94237ec29a7f5
-  data.tar.gz: 3a5f9fcbc1939b84be71dea74a914039c5a8bbfd0f5ec60e50e1d6bdd6de1e98
+  metadata.gz: 026bb4b5dc13392c07a775010344d1e1dbd7640b2f5febe49ea4975809ff6dda
+  data.tar.gz: 12f6932095b0d846529fb3fdf07313ea3407e34d8b65ddf082f1a29ab169091e
 SHA512:
-  metadata.gz: 7fdc683e0ba9125b04fa84d18329719a84e40aa8226d9681f9287658f0e636dadb8c401223dadfde2aafbd9e7340bbcc451f933d708c74f1e85c8284e9a84667
-  data.tar.gz: dd589635c37e608fe4be787a1e039540da9bdf6dd31f5cc3b94bc5aded654020b2bcaa43c29c271647f6fe777defb3729dac3390254d0d800b22a81311b6d14d
+  metadata.gz: 4eab1dfa005e1191e97c5628145ece788fb526d1a2170fc71873eb2a9bc18c1d1a40fb4c7c5ef6ee8bfcab004e04257a01f4c74702acced3a8d73c660945ae95
+  data.tar.gz: e01c42d911488fd9a4a3c71f692d895b6b282f944eb76ad1a154e0834b49f1503d40b29761e0f6c76f5a0d8fa87768fe45ff46eca1b39386e299181cdf4106c2

data/.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+tab_width = 4

data/.github/workflows/ci.yml

@@ -5,55 +5,23 @@ on:
   push:
     branches: [ main ]
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
 permissions:
   contents: read
   pull-requests: read
 
 jobs:
-  lint:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@7372622e62b60b3cb750dcd2b9e32c247ffec26a # v1.302.0
-        with:
-          ruby-version: 3.4.4
-          bundler-cache: true
-
-      - name: Security scan with Brakeman
-        run: bundle exec brakeman --no-pager --quiet
-      - name: Audit gem dependencies for CVEs (bundler-audit)
-        run: bundle exec bundler-audit check --update
-      - name: Lint code for consistent style
-        run: bundle exec rubocop -f github
-
-  test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@7372622e62b60b3cb750dcd2b9e32c247ffec26a # v1.302.0
-        with:
-          ruby-version: 3.4.4
-          bundler-cache: true
-
-      - name: Run tests
-        env:
-          RAILS_ENV: test
-        run: |
-          if find spec -name '*_spec.rb' 2>/dev/null | grep -q .; then
-            bundle exec rspec
-          else
-            echo "No spec files found, skipping."
-          fi
+  ci:
+    uses: rarebit-one/.github/.github/workflows/reusable-gem-ci.yml@v1
+    with:
+      ruby-versions: '["4.0.0","4.0.1","4.0.2","4.0.3"]'
+      lint-ruby-version: "4.0.3"
+      lint-command: bundle exec rubocop --config .rubocop.yml -f github
+      extra-lint-commands: |
+        bundle exec brakeman --no-pager --quiet
+        bundle exec bundler-audit check --update
+      test-command: |
+        if find spec -name '*_spec.rb' 2>/dev/null | grep -q .; then
+          bundle exec rspec
+        else
+          echo "No spec files found, skipping."
+        fi

data/.github/workflows/codeql.yml

@@ -0,0 +1,27 @@
+name: CodeQL
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (Ruby)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: github/codeql-action/init@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4
+        with:
+          languages: ruby
+      - uses: github/codeql-action/analyze@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4
+        with:
+          category: "/language:ruby"
+

data/.github/workflows/release.yml

@@ -5,85 +5,12 @@ on:
     tags:
       - "v*"
 
-permissions:
-  contents: write
-
 jobs:
-  # CI is not gated here — branch protection ensures CI passes before
-  # merge to main, and tags are only pushed after the version bump PR
-  # is merged. Running CI again on tag push is redundant.
   release:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.4.4"
-
-      - name: Verify tag matches gem version
-        run: |
-          tag_version="${GITHUB_REF_NAME#v}"
-          gem_version=$(ruby -e "spec = Gem::Specification.load(Dir['*.gemspec'].first); puts spec.version")
-          if [ "$tag_version" != "$gem_version" ]; then
-            echo "::error::Tag version ($tag_version) does not match gemspec version ($gem_version)"
-            exit 1
-          fi
-
-      - name: Extract changelog entry
-        id: changelog
-        run: |
-          version="${GITHUB_REF_NAME#v}"
-          notes=$(awk -v ver="$version" '
-            /^## \[/ {
-              if (found) exit
-              if ($0 ~ "^## \\[" ver "\\]") found=1
-              next
-            }
-            found { print }
-          ' CHANGELOG.md)
-
-          if [ -z "$notes" ]; then
-            echo "::error::No CHANGELOG.md entry found for version $version"
-            exit 1
-          fi
-
-          # Use a random delimiter to prevent injection via changelog content
-          delimiter="EOF_$(openssl rand -hex 8)"
-          {
-            echo "notes<<${delimiter}"
-            echo "$notes"
-            echo "${delimiter}"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Create GitHub Release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          RELEASE_NOTES: ${{ steps.changelog.outputs.notes }}
-        run: |
-          printf "%s" "$RELEASE_NOTES" > /tmp/release_notes.txt
-          gh release create "$GITHUB_REF_NAME" \
-            --title "$GITHUB_REF_NAME" \
-            --notes-file /tmp/release_notes.txt
-
-  publish:
-    needs: release
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    environment: rubygems
+    uses: rarebit-one/.github/.github/workflows/reusable-gem-release.yml@v1
+    with:
+      gem-name: ground_control-api
+      ruby-version: "4.0.1"
     permissions:
-      contents: read
+      contents: write
       id-token: write
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.4.4"
-          bundler-cache: true
-
-      - name: Push to RubyGems
-        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md - AI Agent Guide for GroundControl::Api
+
+GroundControl::Api is a Rails engine providing a headless JSON API for
+managing Active Job queues, jobs, workers, and recurring tasks on top of
+`mission_control-jobs`. It is the foundation for `ground_control-inertia`
+(which adds an Inertia.js + React UI) but can be used standalone.
+
+## Quick Reference
+
+```bash
+# Run the full spec suite
+bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/path/to/foo_spec.rb
+
+# Lint
+bundle exec rubocop
+
+# Auto-fix lint issues
+bundle exec rubocop -A
+
+# Security checks
+bundle exec brakeman --no-pager
+bundle exec bundler-audit --update
+```
+
+`Gemfile.lock` is gitignored — `bundle install` regenerates it locally and
+in CI.
+
+## Project Structure
+
+```
+ground_control-api/
+├── app/
+│   ├── controllers/ground_control/api/
+│   │   ├── application_controller.rb       # JSON API base
+│   │   ├── applications_controller.rb      # Mission Control applications
+│   │   ├── queues_controller.rb            # Queue listing + pause toggle
+│   │   ├── queues/pauses_controller.rb     # Nested pause/resume action
+│   │   ├── jobs_controller.rb              # Job index/show
+│   │   ├── retries_controller.rb           # Single-job retry
+│   │   ├── bulk_retries_controller.rb      # Bulk retry
+│   │   ├── discards_controller.rb          # Single-job discard
+│   │   ├── bulk_discards_controller.rb     # Bulk discard
+│   │   ├── dispatches_controller.rb        # Force-dispatch scheduled jobs
+│   │   ├── workers_controller.rb           # Worker process listing
+│   │   ├── recurring_tasks_controller.rb   # Recurring task listing
+│   │   ├── features_controller.rb          # Adapter capability flags
+│   │   └── concerns/                       # error_handling, job_filters,
+│   │                                       # adapter_features
+│   └── resources/ground_control/api/
+│       ├── application_resource.rb         # Alba serializers
+│       ├── base_resource.rb
+│       ├── job_resource.rb
+│       ├── page_resource.rb                # Pagination wrapper
+│       ├── queue_resource.rb
+│       ├── recurring_task_resource.rb
+│       ├── server_resource.rb              # Worker/server detail
+│       └── worker_resource.rb
+├── config/
+│   └── routes.rb                           # JSON API surface
+├── lib/ground_control/api/
+│   ├── engine.rb                           # Wires middleware, requires
+│   │                                       # mission_control-jobs engine
+│   └── version.rb
+└── spec/
+    └── spec_helper.rb
+```
+
+## Key Patterns
+
+### Engine boot
+
+`GroundControl::Api::Engine` isolates the `GroundControl::Api` namespace and
+requires `mission_control/jobs/engine` after initialize so all of Mission
+Control's Active Record-style models are available without forcing the host
+app to mount the upstream UI engine. `ActionDispatch::Flash` and
+`Rack::MethodOverride` are inserted as middleware so the API can be mounted
+under the same Rails stack as a host app without surprise.
+
+### Resources (Alba)
+
+Every JSON response goes through an Alba resource under
+`app/resources/ground_control/api/`. `ApplicationResource` is the base for
+gem-specific concerns; individual resources (e.g. `JobResource`,
+`QueueResource`) define the public attribute set. `PageResource` wraps a
+collection plus pagination metadata for index endpoints.
+
+### Controllers
+
+Controllers inherit from `GroundControl::Api::ApplicationController`, which
+forces JSON responses and includes the `ErrorHandling`, `JobFilters`, and
+`AdapterFeatures` concerns. Mutation endpoints (retries, discards,
+dispatches, queue pauses) are namespaced as separate controllers per REST
+resource rather than as custom actions on the parent.
+
+### Adapter feature detection
+
+`AdapterFeatures` exposes which capabilities the active Active Job adapter
+supports (e.g. recurring tasks, bulk operations). The `FeaturesController`
+returns this map so a UI client can hide controls the underlying queue
+backend cannot service.
+
+## Common Workflows
+
+### Adding a new endpoint
+
+1. Add the route under `config/routes.rb` inside the engine's namespace.
+2. Create or extend a controller under `app/controllers/ground_control/api/`.
+3. Define an Alba resource for the response shape under
+   `app/resources/ground_control/api/`.
+4. Add a request spec under `spec/requests/`.
+
+### Running against a host app
+
+The engine assumes Rails 8.0+ and `mission_control-jobs >= 0.6`. Mount it
+in a host app with:
+
+```ruby
+mount GroundControl::Api::Engine, at: "/ground_control/api"
+```
+
+The host app provides the Active Job adapter, queue store, and any
+authentication via Rails' standard middleware stack — this engine
+intentionally has no auth opinions.
+
+## Testing
+
+- RSpec via `rspec-rails`. `spec/spec_helper.rb` is currently minimal —
+  request specs that drive the engine through a dummy host app should be
+  added under `spec/requests/`.
+- Lefthook pre-push runs whitespace + signature checks, RuboCop on `*.rb`,
+  and `rspec --fail-fast`.
+
+## Security Notes
+
+- Brakeman and bundler-audit run in CI (`extra-lint-commands` of the
+  reusable `reusable-gem-ci.yml@v1` workflow) and as pre-push lefthook
+  steps.
+- The engine deliberately ships no authentication — host apps are
+  responsible for protecting the mount point with their existing auth
+  middleware.
+
+## Key Files
+
+| File                                                | Purpose                                         |
+|-----------------------------------------------------|-------------------------------------------------|
+| `lib/ground_control/api/engine.rb`                  | Engine wiring + middleware                      |
+| `lib/ground_control/api/version.rb`                 | Gem version                                     |
+| `app/controllers/ground_control/api/application_controller.rb` | JSON API base controller         |
+| `app/controllers/concerns/ground_control/api/error_handling.rb`| Shared rescue + JSON error shape |
+| `app/controllers/concerns/ground_control/api/job_filters.rb`   | Index filtering / sorting       |
+| `app/controllers/concerns/ground_control/api/adapter_features.rb` | Capability detection         |
+| `app/resources/ground_control/api/application_resource.rb`     | Alba base resource              |
+| `app/resources/ground_control/api/page_resource.rb`            | Pagination wrapper              |
+| `config/routes.rb`                                  | JSON API surface                                |
+| `.github/workflows/ci.yml`                          | Reusable CI shim                                |
+| `.github/workflows/release.yml`                     | Reusable release shim                           |
+| `lefthook.yml`                                      | Pre-push hooks                                  |
+
+## Dependencies
+
+- **rails** — `>= 8.0`
+- **mission_control-jobs** — `>= 0.6`
+- **alba** — `>= 3.0` (JSON serialization)
+
+Dev / test:
+
+- **rspec-rails** — test framework
+- **rubocop-rails-omakase** — linting
+- **brakeman**, **bundler-audit** — security scanners
+- **lefthook** — git hook manager

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-29
+
+### Changed
+
+- CI and release workflows migrated to the shared `rarebit-one/.github` reusable workflows (`reusable-gem-ci.yml@v1`, `reusable-gem-release.yml@v1`); `.github/workflows/ci.yml` and `release.yml` are now thin shims.
+
+### Removed
+
+- **BREAKING:** Dropped support for Ruby < 4.0. `required_ruby_version` is now `>= 4.0` (was `>= 3.2`). Hosts must upgrade to Ruby 4.0+ before bundling this version. CI tests all four published 4.0.x patches. Aligns with the org-wide Ruby 4 policy ([rarebit-one/standard_id#195](https://github.com/rarebit-one/standard_id/pull/195)).
+- **BREAKING:** Dropped support for Rails < 8.0. The `rails` constraint is now `>= 8.0` (was `>= 7.1`). Hosts on Rails 7.x must upgrade to Rails 8.0+ before bundling this version. Aligns with the org-wide policy of supporting Rails 8 and up.
+
 ## [0.1.0] - 2026-04-21
 
 ### Added

data/README.md

@@ -2,13 +2,13 @@
 
 A headless JSON API Rails engine for managing Active Job queues, jobs, workers, and recurring tasks. Built on top of [mission_control-jobs](https://github.com/rails/mission_control-jobs) for the adapter and query layer.
 
-Use standalone for custom frontends, or as the foundation for [ground_control-inertia](https://github.com/rarebit-one/ground-control-inertia).
+Use standalone for custom frontends, or as the foundation for [ground_control-inertia](https://github.com/rarebit-one/ground_control-inertia).
 
 ## Installation
 
 ```ruby
 # Gemfile
-gem "ground_control-api", github: "rarebit-one/ground-control-api"
+gem "ground_control-api", github: "rarebit-one/ground_control-api"
 ```
 
 ## Setup

data/lib/ground_control/api/version.rb

@@ -2,6 +2,6 @@
 
 module GroundControl
   module Api
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/spec/spec_helper.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require "simplecov"
+SimpleCov.start do
+  enable_coverage :branch
+  add_filter "/spec/"
+end
+
 RSpec.configure do |config|
   config.expect_with :rspec do |expectations|
     expectations.include_chain_clauses_in_custom_matcher_descriptions = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ground_control-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -43,14 +43,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: A Rails engine providing a JSON API layer on top of mission_control-jobs.
   Use standalone or as the foundation for ground_control-inertia.
 email:
@@ -59,11 +73,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
 - ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
 - ".github/workflows/codeql-actions.yml"
+- ".github/workflows/codeql.yml"
 - ".github/workflows/release.yml"
 - ".lefthook/bundle-sync.sh"
 - ".lefthook/lib/git-upstream.sh"
@@ -71,6 +87,7 @@ files:
 - ".lefthook/whitespace-check.sh"
 - ".rspec"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - MIT-LICENSE
@@ -107,14 +124,14 @@ files:
 - lib/ground_control/api/version.rb
 - sig/ground_control/api.rbs
 - spec/spec_helper.rb
-homepage: https://github.com/rarebit-one/ground-control-api
+homepage: https://github.com/rarebit-one/ground_control-api
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/rarebit-one/ground-control-api
-  source_code_uri: https://github.com/rarebit-one/ground-control-api
-  changelog_uri: https://github.com/rarebit-one/ground-control-api/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/rarebit-one/ground-control-api/issues
+  homepage_uri: https://github.com/rarebit-one/ground_control-api
+  source_code_uri: https://github.com/rarebit-one/ground_control-api
+  changelog_uri: https://github.com/rarebit-one/ground_control-api/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rarebit-one/ground_control-api/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -122,14 +139,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Headless JSON API for managing Active Job queues, jobs, workers, and recurring
   tasks