forge-ci 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a166543ba3eb11eba412ad6a1488205fdd51b11703eb4ea522eeb5727333d68b
-  data.tar.gz: 12c496c7424ed9e70ef7228729e7f141bf284215982fe68f5e9d3f932415a861
+  metadata.gz: e4eb67b03367a19fc6064a2c043904d02d1cac933df0171c1a6ee07afbfc34dd
+  data.tar.gz: 3b16df7a68a3db78683194662013c0760ca2285513ad562c5adf6f12ac2220f0
 SHA512:
-  metadata.gz: 940643ae6f6727d66ea805520d04d4fba76c1e6232c70489f74d67240c99dde23cedcde86295c452bb9bbddcea0f91905614bf0b98d5d6c882965d206e73809d
-  data.tar.gz: 92674d70e31a78dd2f4bef0843df59a724d387d0a64865f6c756851724795123a1849316b2c63d8dc648f58476e2583917bb9b1095e89d3c04e3ab53b1076248
+  metadata.gz: 19d3a8d7e869fa4682a4a3565fe52956df8de6769ea6d3f2574e523d5379d78d394457471ecda1a6eaa12590087f159c1ddda2dbe21bffc2f5cc9c44b133af40
+  data.tar.gz: 3a47c508f61583bd7fc84d3d96ad28f5b92e9379fbf2b9ca38741c1416c1b4fec7330a3a104906cb85378614b600880ef00e376ae13bbbb9666c80c975e32b89

data/CHANGELOG.md

@@ -6,6 +6,14 @@ separately.
 
 ## Unreleased
 
+## 0.5.0 (2026-10-26)
+
+- Add `forge-ci pipelines --project NAME` to discover existing automatic runs
+  with branch/SHA filters, plus `forge-ci status ID [--wait]` to inspect and
+  watch workflow/job states without triggering another run. Both support
+  saved OAuth sessions and JSON output. Add member-readable bounded project
+  pipeline listing API; existing status-by-ID API remains unchanged.
+
 - Admin **Settings → Runners** shows per-process online/busy/offline presence,
   hostname, implementation, class, trust pool, last contact and current job.
   Updated Ruby and Go runners report via existing claim polls and job heartbeats;

data/README.md

@@ -95,6 +95,22 @@ for upgrade requirements and the 120-second offline threshold.
 - **From any script or CI:** the same `forge-ci trigger` with the
   `FORGE_CI_URL` / `FORGE_CI_ADMIN_TOKEN` environment variables.
 
+Inspect automatically triggered runs without starting another pipeline:
+
+```sh
+export FORGE_CI_URL=https://ci.example.com
+forge-ci login
+forge-ci pipelines --project owner/repo --branch main
+forge-ci status 42
+forge-ci status 42 --wait
+```
+
+`pipelines` lists recent runs newest first; use an ID from that list with
+`status` to see workflows/jobs. `--wait` watches that existing run and exits
+nonzero if it fails or is canceled. Both commands accept `--json` and reuse
+your saved login; members can inspect runs. Deploy the updated control plane
+for pipeline listing.
+
 Check a config locally first; the compiler needs only Ruby 3.0+. `gem install`
 puts the `forge-ci` CLI on your PATH:
 

data/lib/forge_ci/cli.rb

@@ -36,7 +36,7 @@ module ForgeCI
               [--manual]                            sign in to a forge-ci server
                                                     in the browser (OAuth); the
                                                     token is stored and picked
-                                                    up by trigger/cancel
+                                                    up by server commands
                                                     (URL defaults to FORGE_CI_URL;
                                                     --manual pastes a code instead
                                                     of waiting on the browser)
@@ -54,6 +54,15 @@ module ForgeCI
                                                     checkout; --wait blocks until
                                                     it finishes and exits 1 if it
                                                     did not succeed)
+        pipelines --project P [--branch B] [--sha SHA] [--limit N]
+                  [--json] [--url URL] [--token T]   list existing pipelines
+                                                    (default limit 20, max 100)
+        status <pipeline-id> [--wait] [--poll SECONDS] [--json]
+               [--url URL] [--token T]              show pipeline/workflow/jobs;
+                                                    --wait watches changes and
+                                                    exits 1 on failure/cancel;
+                                                    --json emits one final JSON
+                                                    (poll default 5 seconds)
         cancel <pipeline-id> [--url URL] [--token T]
                                                     cancel a running pipeline
         skill install [--dir DIR] [--force]         install the forge-ci agent
@@ -91,6 +100,8 @@ module ForgeCI
       when "login" then login_command(argv)
       when "logout" then logout_command(argv)
       when "trigger" then trigger_command(argv)
+      when "pipelines" then pipelines_command(argv)
+      when "status" then status_command(argv)
       when "cancel" then cancel_command(argv)
       when "skill" then skill_command(argv)
       when "-h", "--help", nil then help
@@ -360,6 +371,119 @@ module ForgeCI
       end
     end
 
+    # -- Read existing pipelines without triggering another run. --------------
+
+    def pipelines_command(argv)
+      options = { url: ENV["FORGE_CI_URL"], token: ENV["FORGE_CI_ADMIN_TOKEN"], limit: "20" }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: forge-ci pipelines --project P [--branch B] [--sha SHA] [--limit N] [--json] [--url URL] [--token T]"
+        opts.on("--project P", "project id or name on the server") { |v| options[:project] = v }
+        opts.on("--branch B", "filter by branch") { |v| options[:branch] = v }
+        opts.on("--sha SHA", "filter by commit sha") { |v| options[:sha] = v }
+        opts.on("--limit N", "maximum results (1-100, default 20)") { |v| options[:limit] = v }
+        opts.on("--json", "print JSON") { options[:json] = true }
+        opts.on("--url URL", "server base URL (env FORGE_CI_URL)") { |v| options[:url] = v }
+        opts.on("--token T", "bearer token (env FORGE_CI_ADMIN_TOKEN, or forge-ci login)") { |v| options[:token] = v }
+        opts.on("-h", "--help", "show this help and exit") do
+          @out.puts opts
+          return 0
+        end
+      end
+      parser.parse!(argv)
+      return usage_error("pipelines takes no positional arguments") unless argv.empty?
+      return usage_error("--project is required") if options[:project].to_s.empty?
+      if options[:project].match?(/\A\d+\z/) && options[:project].to_i.zero?
+        return usage_error("--project id must be positive")
+      end
+      unless options[:limit].match?(/\A\d+\z/) && (1..100).cover?(options[:limit].to_i)
+        return usage_error("--limit must be an integer between 1 and 100")
+      end
+      err = server_options_error(options)
+      return usage_error(err) if err
+
+      project_id = resolve_project_id(options)
+      query = URI.encode_www_form(options.slice(:branch, :sha, :limit))
+      result = api_request(options, :get, "/api/v1/projects/#{project_id}/pipelines?#{query}")
+      if options[:json]
+        @out.puts JSON.generate(result)
+      elsif result.fetch("pipelines").empty?
+        @out.puts "forge-ci: no pipelines found"
+      else
+        @out.puts "ID\tSTATUS\tBRANCH\tSHA"
+        result.fetch("pipelines").each do |pipeline|
+          @out.puts pipeline.values_at("id", "status", "branch", "sha").join("\t")
+        end
+      end
+      0
+    rescue OptionParser::ParseError => e
+      usage_error(e.message)
+    rescue ApiError => e
+      @err.puts "forge-ci: #{e.message}"
+      1
+    end
+
+    def status_command(argv)
+      options = { url: ENV["FORGE_CI_URL"], token: ENV["FORGE_CI_ADMIN_TOKEN"], poll: 5.0 }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: forge-ci status <pipeline-id> [--wait] [--poll SECONDS] [--json] [--url URL] [--token T]"
+        opts.on("--wait", "watch until the pipeline finishes") { options[:wait] = true }
+        opts.on("--poll SECONDS", Float, "positive poll interval (default 5)") { |v| options[:poll] = v }
+        opts.on("--json", "print one JSON response (final response with --wait)") { options[:json] = true }
+        opts.on("--url URL", "server base URL (env FORGE_CI_URL)") { |v| options[:url] = v }
+        opts.on("--token T", "bearer token (env FORGE_CI_ADMIN_TOKEN, or forge-ci login)") { |v| options[:token] = v }
+        opts.on("-h", "--help", "show this help and exit") do
+          @out.puts opts
+          return 0
+        end
+      end
+      parser.parse!(argv)
+      id = argv.shift
+      unless id && id.match?(/\A\d+\z/) && id.to_i.positive?
+        return usage_error("status requires a positive integer <pipeline-id>")
+      end
+      return usage_error("status takes exactly one <pipeline-id> argument") unless argv.empty?
+      unless options[:poll].finite? && options[:poll].positive?
+        return usage_error("--poll must be a positive finite number of seconds")
+      end
+      err = server_options_error(options)
+      return usage_error(err) if err
+
+      last = {}
+      loop do
+        pipeline = api_request(options, :get, "/api/v1/pipelines/#{id.to_i}")
+        last = print_pipeline_status(pipeline, last) unless options[:json]
+        terminal = !%w[pending running].include?(pipeline["status"])
+        unless options[:wait] && !terminal
+          @out.puts JSON.generate(pipeline) if options[:json]
+          return options[:wait] && pipeline["status"] != "success" ? 1 : 0
+        end
+        sleep options[:poll]
+      end
+    rescue OptionParser::ParseError => e
+      usage_error(e.message)
+    rescue ApiError => e
+      @err.puts "forge-ci: #{e.message}"
+      1
+    end
+
+    def print_pipeline_status(pipeline, last)
+      if last.empty?
+        @out.puts "forge-ci: branch #{pipeline["branch"]} sha #{pipeline["sha"]}"
+      end
+      states = { "pipeline #{pipeline["id"]}" => pipeline["status"] }
+      Array(pipeline["workflows"]).each do |workflow|
+        label = "workflow #{workflow["id"]} (#{workflow["name"]})"
+        states[label] = workflow["status"]
+        Array(workflow["jobs"]).each do |job|
+          states["#{label} job #{job["id"]} (#{job["name"]}[#{job["node_index"]}])"] = job["status"]
+        end
+      end
+      states.each do |label, status|
+        @out.puts "forge-ci: #{label}: #{status}" if last[label] != status
+      end
+      states
+    end
+
     # -- forge-ci cancel <pipeline-id> ----------------------------------------
 
     def cancel_command(argv)

data/lib/forge_ci.rb

@@ -16,5 +16,5 @@ require_relative "forge_ci/compiler"
 # JSON-serializable intermediate representation (IR) that a scheduler and
 # runner can execute. Pure Ruby, stdlib only, no network, no processes.
 module ForgeCI
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/skills/forge-ci/SKILL.md

@@ -148,14 +148,21 @@ commands in the job images.
 
 ## Run, watch and cancel
 
-Pipelines normally start on push. For manual runs, sign in with your web-UI
-account. Triggering requires an admin; members can view and cancel.
+Pipelines normally start on push. Inspect that existing run before considering
+`trigger`: triggering again creates duplicate work and can repeat deployments.
+Sign in with your web-UI account. Triggering requires an admin; members can
+list, inspect, watch and cancel.
 
 ```sh
 export FORGE_CI_URL=https://ci.example.com
 forge-ci login
 # Over SSH/headless: forge-ci login --manual
 
+# Inspect automatic runs; these commands never trigger a new pipeline.
+forge-ci pipelines --project owner/repo --branch main
+forge-ci status <id>
+forge-ci status <id> --wait
+
 # Starts a pipeline for the current branch and HEAD; push the commit first.
 # --wait blocks and exits non-zero on failure.
 forge-ci trigger .circleci/config.yml --project owner/repo --wait
@@ -163,6 +170,32 @@ forge-ci cancel <id>
 forge-ci logout
 ```
 
+`pipelines` lists the newest 20 runs (use `--limit 1..100`, `--branch`, or
+exact `--sha` to narrow it). `status` prints workflow/job states; `--wait`
+watches the selected ID and exits 0 on success, 1 on failure/cancellation.
+A one-shot status read exits 0 even for a failed run. `--poll SECONDS` sets
+watch interval (positive, default 5). Both commands accept `--json`; watching
+with JSON emits only the final pipeline document. Members can read these
+commands; pipeline listing requires the updated server.
+
+For a pushed commit, select the exact run rather than watching an unrelated
+latest pipeline:
+
+```sh
+forge-ci pipelines --project owner/repo --sha "$(git rev-parse HEAD)" --json
+# Choose the returned pipeline ID matching the intended branch/run.
+forge-ci status 42 --wait --poll 5
+```
+
+An empty list is not permission to trigger: check the server URL, project,
+commit push and GitHub webhook delivery first. Multiple runs can share a SHA;
+confirm the intended ID. `--sha` requires the full exact SHA, not its short form.
+Check `forge-ci --help` for `pipelines` and `status` before using them: an older
+installed gem may lack these commands even if OAuth login works. Upgrade to a
+release containing them, or run the updated checkout with
+`ruby -Ilib exe/forge-ci`. If listing returns `404`, verify the server deploy;
+status by a known ID uses the existing API. Do not substitute `trigger --wait`.
+
 Login uses authorization-code + PKCE. Credentials live per server in
 `~/.config/forge-ci/credentials.json` (0600), or `FORGE_CI_CREDENTIALS`;
 `XDG_CONFIG_HOME` changes the default config directory. Tokens refresh

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge-ci
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Azmi Muwahid