5pm 0.1.0

data/docs/releasing.md

@@ -0,0 +1,154 @@
+# Release preparation
+
+`bin/package` builds the gem, checks its exact file inventory and MIT license, then
+loads the installed artifact in a subprocess outside Bundler's source checkout.
+It does not publish. `bin/release-check VERSION FULL_COMMIT_SHA` is also read-only.
+
+## Owner-controlled live validation
+
+Stan Carver II decides when another live API check is useful. Live API access,
+an active trial or paid subscription, Keychain credentials, and fresh live evidence
+are not release prerequisites. The 15-day trial does not create an ongoing account
+requirement. Releases and CI use offline tests, stored contracts, package verification
+and maintainer acceptance of the exact candidate.
+
+Historical reports retain their actual outcomes and tested source. Do not relabel
+an old report as a fresh check. `bin/validate` reuses its local sanitized report
+without expiration or network requests, even if source changes; `source_matches`
+indicates whether its fingerprint still matches. Only an explicit owner-requested
+refresh contacts 5PM. See [cached validation](cached-validation.md).
+
+Before a release:
+
+1. Review the source and matching core/MCP versions, and date the changelog.
+2. Pass `bin/spec`, `bin/lint --cache false`, and `bin/package-mcp` offline.
+3. Merge reviewed changes through PRs with passing CI. Fetch origin/master and tags.
+4. Run `bin/release-check VERSION FULL_COMMIT_SHA` from a clean checkout. It checks
+   accepted source ancestry, matching versions, the dated changelog and conflicting
+   tags. It does not contact 5PM or require `docs/live-validation.json`.
+5. Rebuild from the accepted source, inspect both artifacts and independently accept
+   their hashes. Recheck gem-name availability and obtain maintainer publication
+   approval. Publish the exact accepted bytes, core first and then MCP.
+
+Optional live checks remain available when the owner requests them. If used, keep
+them outside CI, designate a disposable tenant, and enable mutations separately.
+Record actual results and clean up labelled records; do not invent success receipts.
+See [live validation](live-validation.md). Outstanding API observations can be
+tracked as known issues without imposing a mandatory new live test campaign.
+
+## Connect GitHub and RubyGems once
+
+This follows [abbu's release workflow](https://github.com/scarver2/abbu/blob/4c64d0eb0ccdbc0a8c04b2e50da92594faf75d09/.github/workflows/release.yml)
+(browser dispatch, exact commit, separate tag and publish jobs) and
+[printavo's release workflow](https://github.com/scarver2/printavo-ruby/blob/464ae6f29b8ff7627cf829c02351d1b9eadea37d/.github/workflows/release.yml)
+(pinned RubyGems action and Bundler tasks). Both packages publish through
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/), without a
+long-lived RubyGems API key or GitHub PAT in repository secrets.
+
+A repository administrator must create the
+[release environment](https://github.com/scarver2/5pm-ruby/settings/environments):
+
+- Name: `release`; required reviewer: `scarver2`.
+- Disable administrator bypass. Allow the initiating maintainer to approve, matching abbu.
+- Select deployment branches and tags: branch `master` and tag `v*`, only.
+
+Both owner prerequisites remain required: this protected GitHub `release`
+environment and RubyGems trusted publishers for **both** `5pm` and `5pm-mcp`.
+Workflow environment variables only describe execution context and the selected
+candidate; they are not independent authorization. GitHub's required-reviewer
+approval gate and RubyGems' matching OIDC publisher policies enforce authorization.
+
+The workflow checks these protections before building or tagging. Missing protection
+or inaccessible environment metadata stops the run. The current GitHub connection
+cannot create this environment: GitHub returned HTTP 403, administrator rights required.
+
+Sign into RubyGems.org and create two
+[pending trusted publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+for the first publication:
+
+| Gem name | GitHub owner | Repository | Workflow filename | Environment |
+| --- | --- | --- | --- | --- |
+| `5pm` | `scarver2` | `5pm-ruby` | `release.yml` | `release` |
+| `5pm-mcp` | `scarver2` | `5pm-ruby` | `release.yml` | `release` |
+
+These are separate gem registrations using the same workflow identity. For an
+already-owned gem, configure its trusted publisher instead of a pending publisher.
+Recheck both names for availability before publication. Account setup must
+be completed by the authenticated RubyGems owner; repository configuration alone
+does not establish that connection.
+
+## Shared bin-script conventions
+
+Like abbu and printavo, Bash entrypoints source `bin/_lib.sh`, change to the
+repository root, and select Ruby through mise when available. Run them directly:
+
+```sh
+bin/spec
+bin/lint
+bin/package
+bin/package-mcp
+bin/release-check VERSION FULL_COMMIT_SHA
+```
+
+`bin/package` writes `pkg/5pm-VERSION.gem`; `bin/package-mcp` also writes
+`mcp/pkg/5pm-mcp-VERSION.gem`. Inventory checks live in `bin/verify-package.rb`;
+package installation, smoke checks, and release logic live in Ruby helpers under
+`bin/support/`, following printavo's layout. Temporary installs are removed on exit.
+Dependencies come from the verified bundle, as in abbu, without network installation.
+
+`bin/verify-release-tag` reads `RELEASE_TAG_REF` (or `GITHUB_REF` on tag events), requires `refs/tags/vVERSION`, and
+verifies that the tag matches HEAD and passes the accepted-commit preflight.
+It is read-only. Publication remains the protected workflow's `rake release`.
+
+## Build and approve a release
+
+Standard Bundler tasks build the core and MCP artifacts respectively:
+
+```sh
+bundle exec rake build
+bundle exec rake -f mcp/Rakefile build
+bundle exec rake
+bundle exec rubocop --cache false
+bin/package-mcp
+```
+
+The packaging checks inspect the actual installed artifacts. CI repeats validation
+on Ruby 3.2, 3.3, 3.4 and 4.0. Release builds set `SOURCE_DATE_EPOCH` to the approved
+commit timestamp. Neither build task publishes.
+
+Before dispatch, complete the offline checks and dated changelog above. Both
+gem versions must match. Live reports are optional historical evidence. Preparing
+this workflow does not advance the version, date the changelog or authorize publication.
+
+After merging the workflow, open Actions → **Release gems** → **Run workflow** on
+`master`. Enter the explicitly approved stable version without `v` and its full
+40-character accepted commit SHA. The read-only preflight rejects an unaccepted
+commit, a dirty checkout, an undated changelog, mismatched versions or a conflicting tag.
+Tag pushes never start publication. The only release entry point is manual dispatch
+from `master`; dispatch from any other branch or tag is rejected. Version and full
+commit inputs must identify the explicitly approved candidate.
+
+Approve the protected tag job only after inspecting the candidate summary and
+verification jobs. It creates `vVERSION` only if absent and verifies its exact target;
+it never moves an existing tag. Approve each protected publication job for that same
+candidate. Publishing has OIDC permission and read-only repository contents; only
+the separate tag job can write repository contents. Bundler's source-control push
+action is disabled. Local publishing tasks refuse to run outside this workflow.
+
+The pinned `rubygems/release-gem` action invokes `bundle exec rake release` for the
+core gem, waits for RubyGems availability, then does the same in `mcp/`. The MCP
+package depends on the matching core version. The workflow does not create a GitHub
+Release. No workflow should be dispatched merely to test the connection: a successful
+run publishes both gems.
+
+If core publication succeeds and MCP fails, inspect the published core version and
+provenance, fix the cause, and rerun only the failed jobs against the same approved
+candidate. Do not rerun an already-successful publish job, move the tag, overwrite a
+published version or automatically yank it. Code changes require a new reviewed
+candidate and fresh evidence; arrange a new version when the core is already published.
+
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/examples/read_only.rb

@@ -0,0 +1,12 @@
+require "five_pm"
+
+# Environment variables can be injected by Infisical or another process secret provider.
+client = FivePM::Client.new(host: ENV.fetch("FIVE_PM_HOST"), login: ENV.fetch("FIVE_PM_LOGIN"),
+                            password: ENV.fetch("FIVE_PM_PASSWORD"), response_mode: :typed)
+begin
+  # One bounded request; returned account content may be sensitive.
+  response = client.tasks.list(filter: { projectId: Integer(ENV.fetch("FIVE_PM_PROJECT_ID")) }, count: 20)
+  response.list.each { |task| puts "#{task.id}: #{task.name}" }
+ensure
+  client.sign_out
+end

data/lib/five_pm/client.rb

@@ -0,0 +1,145 @@
+require "json"
+
+module FivePM
+  OPERATIONS = JSON.parse(File.read(File.join(__dir__, "operations.json")))
+  SERVICE_NAMES = { authentication: "authentication", projects: "projects", project_groups: "projectsgroups",
+                    tasks: "tasks", activity: "activity", users: "users" }.freeze
+
+  class Service
+    def initialize(client, name)
+      @client = client
+      @name = name
+    end
+
+    # Parameter names follow the upstream contract exactly; unknown fields inside
+    # complex objects are preserved. Responses remain intact until JSON is verified.
+    def call(operation, **parameters)
+      @client.call(@name, operation, **parameters)
+    end
+
+    def inspect
+      "#<FivePM::Service #{@name}>"
+    end
+  end
+
+  require_relative "resource"
+  require_relative "services"
+
+  class Client
+    SESSION_TTL = 30 * 60
+
+    def initialize(host:, login:, password:, open_timeout: 5, read_timeout: 30, write_timeout: 30,
+                   response_mode: :raw, read_retries: 0, max_retry_delay: 30, max_response_bytes: 5 * 1024 * 1024,
+                   transport: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      unless [login, password].all? { |value| value.is_a?(String) && !value.empty? }
+        raise ConfigurationError, "login and password must be nonempty strings"
+      end
+
+      raise ConfigurationError, "response_mode must be :raw or :typed" unless %i[raw typed].include?(response_mode)
+
+      @retry_policy = RetryPolicy.new(max_retries: read_retries, max_delay: max_retry_delay)
+      @response_mode = response_mode
+      validated = Transport.new(host: host, open_timeout: open_timeout, read_timeout: read_timeout,
+                                write_timeout: write_timeout, max_response_bytes: max_response_bytes)
+      @transport = transport || validated
+      @login = login.dup.freeze
+      @password = password.dup.freeze
+      @clock = clock
+      @mutex = Mutex.new
+      @services = SERVICE_NAMES.to_h do |name, wire|
+        type = { authentication: Authentication, users: Users, activity: Activity }.fetch(name, Resource)
+        [name, type.new(self, wire)]
+      end
+    end
+
+    SERVICE_NAMES.each_key { |name| define_method(name) { @services.fetch(name) } }
+
+    def call(service, operation, **parameters)
+      contract = OPERATIONS.dig(service.to_s, operation.to_s)
+      raise ArgumentError, "unsupported 5pm operation" unless contract
+      if service.to_s == "authentication" && %w[signIn signOut].include?(operation.to_s)
+        raise ArgumentError, "use Client#sign_in or Client#sign_out"
+      end
+
+      params = parameters.transform_keys(&:to_s)
+      allowed = contract.fetch("parameters").keys - %w[sessionId login password]
+      raise ArgumentError, "unsupported parameter names" unless (params.keys - allowed).empty?
+
+      Request.operation!(service.to_s, operation.to_s, params)
+      token = @mutex.synchronize { session_id } if contract.fetch("parameters").key?("sessionId")
+      params["sessionId"] = token if token
+      binary = service.to_s == "activity" && operation.to_s == "downloadFile"
+      begin
+        payload = @retry_policy.call(service.to_s, operation.to_s) do
+          binary ? @transport.download_file(params) : @transport.post(service.to_s, operation.to_s, params)
+        end
+      rescue AuthenticationError
+        @mutex.synchronize { @session_id = nil if @session_id == token }
+        raise
+      end
+      return payload if binary
+
+      # Injected transports may return unchecked JSON. Keep this public boundary
+      # safe as well as Transport's direct-call boundary.
+      APIResult.check!(payload)
+      @response_mode == :typed ? Response.new(payload, contract: contract) : payload
+    end
+
+    def sign_in
+      @mutex.synchronize do
+        @session_id = nil
+        session_id
+      end
+      self
+    end
+
+    def download_file(id)
+      call("activity", "downloadFile", id: id, stream: false)
+    end
+
+    def sign_out
+      @mutex.synchronize do
+        return false unless @session_id
+
+        begin
+          payload = @transport.post("authentication", "signOut", { "sessionId" => @session_id })
+          APIResult.check!(payload)
+          contract = OPERATIONS.fetch("authentication").fetch("signOut")
+          @response_mode == :typed ? Response.new(payload, contract: contract) : payload
+        ensure
+          @session_id = nil
+        end
+      end
+    end
+
+    def marshal_dump
+      raise TypeError, "FivePM clients cannot be serialized"
+    end
+
+    def inspect
+      "#<FivePM::Client>"
+    end
+
+    private
+
+    def session_id
+      return @session_id if @session_id && @clock.call < @expires_at
+
+      @session_id = nil
+      started = @clock.call
+      response = @transport.post("authentication", "signIn", { "login" => @login, "password" => @password })
+      APIResult.check!(response)
+      # The test tenant returns data.sessionId; retain the WSDL-shaped envelope
+      # for compatibility. Reject ambiguous responses rather than picking a token.
+      envelopes = response.is_a?(Hash) ? %w[data auth].select { |key| response.key?(key) } : []
+      envelope = response[envelopes.first] if envelopes.length == 1
+      token = envelope["sessionId"] if envelope.is_a?(Hash)
+      unless token.is_a?(String) && !token.empty?
+        raise ProtocolError, "5pm signIn response did not contain an unambiguous sessionId"
+      end
+
+      @expires_at = started + SESSION_TTL - 30
+      @session_id = token
+    end
+  end
+end

data/lib/five_pm/download.rb

@@ -0,0 +1,16 @@
+module FivePM
+  # Explicit access to bounded binary data; inspection never includes its contents.
+  class Download
+    attr_reader :bytes, :content_type
+
+    def initialize(bytes:, content_type:)
+      @bytes = bytes.b.freeze
+      @content_type = content_type&.dup&.freeze
+      freeze
+    end
+
+    def inspect
+      "#<FivePM::Download>"
+    end
+  end
+end

data/lib/five_pm/errors.rb

@@ -0,0 +1,73 @@
+module FivePM
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class TransportError < Error; end
+  class ProtocolError < Error; end
+
+  class SchemaError < ProtocolError
+    attr_reader :field, :expected_type, :actual_type
+
+    def initialize(field:, expected_type:, value:)
+      @field = field.dup.freeze
+      @expected_type = expected_type.dup.freeze
+      @actual_type = case value
+                     when Hash then "object"
+                     when Array then "array"
+                     when String then "string"
+                     when Numeric then "number"
+                     when true, false then "boolean"
+                     when nil then "null"
+                     else "unknown"
+                     end.freeze
+      super("5pm response contains an invalid schema field")
+    end
+  end
+
+  class AuthenticationError < Error; end
+
+  class APIError < Error
+    attr_reader :code
+
+    def initialize(code)
+      @code = code
+      super("5pm API request failed (code #{code})")
+    end
+  end
+
+  module APIResult
+    def self.check!(payload)
+      if payload.is_a?(Hash) && payload["code"].is_a?(Integer) && payload["message"].is_a?(String) &&
+         (!payload.key?("data") || payload["code"] >= 400)
+        raise APIError, payload.fetch("code")
+      end
+
+      payload
+    end
+  end
+
+  class HTTPError < Error
+    attr_reader :status
+
+    def initialize(status)
+      @status = status
+      super("5pm HTTP request failed (#{status})")
+    end
+  end
+
+  class RateLimitError < HTTPError
+    attr_reader :retry_after
+
+    def initialize(retry_after: nil, retryable: true)
+      @retry_after = retry_after
+      @retryable = retryable
+      super(429)
+    end
+
+    def retryable?
+      @retryable
+    end
+  end
+
+  class NotFoundError < HTTPError; end
+  class ServerError < HTTPError; end
+end