debugbundle 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57ff4962fe1910ae27c974401d207da7c6a1afc1d22f9a5951b93d4c338f1f65
-  data.tar.gz: cb7d91a8088df973a7a4b344c79799e348fb0cbccc0544eac5f898c458bb931b
+  metadata.gz: cd8a77046a7f20cf6971b6e73ca8e5c7557738706e32e3b30e741f3410f8d00a
+  data.tar.gz: 0bd638cf69ff2c6894706b1bc996f801e849b6f5a5c134543a3a18d1c598725f
 SHA512:
-  metadata.gz: 1eaccc22806e5bf4844d7a1820c52f67add73f63025f5023f664570ac64b4fb6ba46e62faeb2d6a8380c95bd7e1c7efd469cfbba4bb4de81613a4b4476305e40
-  data.tar.gz: 55ab0c5a6f38b356ad6a49d580fcf95ac68075f3d9633aabb136c70cd9c8d5f9908a0a38a83eb162cd1387d3ce4ca3edb979bb4b727430306facfda3dd50c145
+  metadata.gz: c9431211f33958cf178a8ace0e01b3842a2a2ff1bed8e11129e053ceb6b8685ff17499d03c80bc3cfe3fc7fd6839eced529ab01238760f04a65f4181e6685507
+  data.tar.gz: f7a432f0dc42da84a44415c767610473d8f332577eeb658c1417e47e4227e2701f7143e67fb9a8fa40db700dfca9f9ba0f655fe270fbd779de0e499507dc6836

data/Makefile

@@ -3,6 +3,7 @@ SHELL := /bin/sh
 RUBY_IMAGE ?= ruby:3.4.2
 WORKDIR := /workspace
 BUNDLE_GEMFILE ?= Gemfile
+VERSION ?= $(shell ruby -e 'require "./lib/debugbundle/version"; print DebugBundle::VERSION')
 
 DOCKER_RUN = docker run --rm -t \
 	-v "$(PWD):$(WORKDIR)" \
@@ -12,6 +13,8 @@ DOCKER_RUN = docker run --rm -t \
 BUNDLE_ENV = BUNDLE_GEMFILE="$(BUNDLE_GEMFILE)"
 
 .PHONY: bundle-install test lint build shell compat-rack compat-rails compat-sidekiq compat
+.PHONY: smoke
+.PHONY: smoke-published
 
 bundle-install:
 	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install"
@@ -25,6 +28,12 @@ lint:
 build:
 	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install && gem build debugbundle.gemspec"
 
+smoke:
+	$(DOCKER_RUN) sh -lc "gem build debugbundle.gemspec && ruby smoke/run_app_driven_smoke.rb --source local --version $(VERSION)"
+
+smoke-published:
+	$(DOCKER_RUN) sh -lc "ruby smoke/run_app_driven_smoke.rb --source published --version $(VERSION)"
+
 compat-rack:
 	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.1.6 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle exec rspec spec/rack_integration_spec.rb spec/rack_middleware_spec.rb spec/relay_spec.rb'
 	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.4.2 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle exec rspec spec/rack_integration_spec.rb spec/rack_middleware_spec.rb spec/relay_spec.rb'

data/README.md

@@ -10,38 +10,33 @@ Use this gem to capture Ruby backend exceptions, request metadata, structured lo
 gem "debugbundle"
 ```
 
-## Quick start
+## Quick Start
 
 ```ruby
 require "debugbundle"
+require "logger"
 
 DebugBundle.init(
-	project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
-	service: "checkout-api",
-	environment: ENV.fetch("APP_ENV", "production")
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api",
+  environment: ENV.fetch("APP_ENV", "production")
 )
 
 DebugBundle.capture_logger(Logger.new($stdout))
-```
-
-`DebugBundle.init(...)` arms best-effort process exception capture automatically through `at_exit` and thread exception hooks.
 
-Capture handled exceptions, messages, requests, and probes explicitly:
-
-```ruby
 begin
-	perform_checkout
+  perform_checkout
 rescue => error
-	DebugBundle.capture_exception(error, context: { order_id: 123 })
+  DebugBundle.capture_exception(error, context: { order_id: 123 })
 end
 
-DebugBundle.capture_log("payment retry failed", level: :warning, context: { order_id: 123 })
 DebugBundle.capture_message("worker started", level: :info)
-DebugBundle.probe("checkout.tax", { region: "us-east-1" })
 DebugBundle.flush
 ```
 
-## Framework integrations
+`DebugBundle.init(...)` arms best-effort process exception capture automatically through `at_exit` and thread exception hooks.
+
+## Framework Integrations
 
 | Surface | Integration |
 | --- | --- |
@@ -52,44 +47,20 @@ DebugBundle.flush
 | Semantic Logger | `DebugBundle.capture_semantic_logger` |
 | Browser relay | `DebugBundle::Relay::Handler` or `DebugBundle::Rack::RelayMiddleware` |
 
-## Browser relay
+## Configuration Reference
 
-Ruby backends can receive browser events at `POST /debugbundle/browser` through the relay handler.
+Configuration sources and precedence:
 
-Rails applications can let the Railtie append that route automatically, or override it with:
+1. Explicit arguments passed to `DebugBundle.init(...)`, `DebugBundle::Client.new(...)`, or `DebugBundle::Relay::Handler.new(...)`.
+2. Rails `config.debugbundle.*` values when the Railtie wires the default client or relay route.
+3. Environment variables only when your application chooses to pass them into those explicit Ruby calls. The gem does not auto-read arbitrary config env vars on its own.
+4. Remote probe directives and capture policy returned by `GET /v1/sdk/config` after a connected client initializes.
 
-- `config.debugbundle.relay_enabled = false` to disable automatic mounting
-- `config.debugbundle.relay_path = "/debugbundle/browser"` to change the mounted path
-- `config.debugbundle.relay_allowed_origins = ["https://app.example.com"]` to pin allowed origins
-- `config.debugbundle.relay_rate_limit_per_minute = 120` to adjust per-IP relay throttling
-- `config.debugbundle.relay_rate_limit_store = Rails.cache` to share relay throttling across processes
-- `config.debugbundle.relay_handler = custom_handler` to supply a custom relay handler
-
-The relay:
-
-- validates same-origin requests by default
-- enforces `Content-Type: application/json`
-- caps request bodies at 256 KB
-- strips browser-supplied credentials and trust-sensitive fields
-- preserves browser correlation fields such as `trace_id`
-- supports local-only event writes and connected durable forwarding
-
-## Remote probes
-
-Probe buffers stay local and flush on captured exceptions by default. Paid-tier projects can also activate probes for immediate `probe_event` shipping through the polled remote config.
-
-For one-off request diagnostics, the Ruby SDK also accepts signed trigger tokens:
-
-- header: `X-DebugBundle-Probe-Trigger: dbundle_probe_...`
-- query parameter: `?_debug_probe=dbundle_probe_...`
-
-Matching probes still stay in the local ring buffer, but the triggered request also emits standalone `probe_event` records immediately when the token is valid.
-
-## Configuration
+Capture-policy fields are server-owned and must not be supplied in local SDK config. The Ruby SDK enforces the server response locally after initialization.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `project_token` | required | Write-only DebugBundle project token. |
+| `project_token` | required for connected capture | Write-only DebugBundle project token used by server-side transport. |
 | `service` | `ruby-service` | Service name used in event envelopes. |
 | `environment` | `development` | Runtime environment. |
 | `endpoint` | `https://api.debugbundle.com/v1/events` | Connected ingestion endpoint. |
@@ -110,7 +81,178 @@ Matching probes still stay in the local ring buffer, but the triggered request a
 | `probe_flush_on_error` | `true` | Attach probe buffers to captured exceptions. |
 | `probes_poll_interval` | `60` | Remote config poll interval in seconds. |
 
-## Safety defaults
+## Install Examples by Mode
+
+### Connected mode
+
+```ruby
+require "debugbundle"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api",
+  environment: "production",
+  endpoint: "https://api.debugbundle.com/v1/events"
+)
+```
+
+### Local-only mode
+
+```ruby
+require "debugbundle"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api",
+  environment: "development",
+  project_mode: :local_only,
+  local_events_dir: ".debugbundle/local/events"
+)
+```
+
+### Rack middleware
+
+```ruby
+require "debugbundle"
+require "rack"
+
+client = DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api",
+  environment: "production"
+)
+
+app = Rack::Builder.new do
+  use DebugBundle::Rack::Middleware, client: client
+
+  run lambda { |_env|
+    [200, { "Content-Type" => "text/plain" }, ["ok"]]
+  }
+end
+```
+
+### Rails initializer
+
+```ruby
+# config/initializers/debugbundle.rb
+require "debugbundle"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api",
+  environment: Rails.env
+)
+
+Rails.application.configure do
+  config.debugbundle.relay_allowed_origins = ["https://app.example.com"]
+end
+```
+
+### Sidekiq server middleware
+
+```ruby
+require "debugbundle"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-worker",
+  environment: ENV.fetch("APP_ENV", "production")
+)
+
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add(DebugBundle::Sidekiq::ServerMiddleware, client: DebugBundle.client)
+  end
+end
+```
+
+### Logger integration
+
+```ruby
+require "debugbundle"
+require "logger"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "checkout-api"
+)
+
+logger = Logger.new($stdout)
+DebugBundle.capture_logger(logger)
+```
+
+## Runtime and Framework Support
+
+| Surface | Minimum compatibility version | Recommended production version | Installed-base compatibility lane | Rolling CI lane | Out of scope |
+| --- | --- | --- | --- | --- | --- |
+| Ruby runtime | 3.1 | current maintained Ruby 3.4.x patch line | 3.1 and 3.2 remain supported for installed-base coverage | 3.1, 3.2, 3.3, 3.4 | 3.0 and older |
+| Rails | 7.0 | latest 7.1 patch line | 7.0 compatibility support | 7.0 and 7.1 | 6.x and older |
+| Rack | 2.2 | latest 3.x patch line | 2.2 compatibility support | 2.2 and 3.x | 2.1 and older |
+| Sidekiq | 7.x | latest 8.x patch line | 7.x compatibility support | 7.x and 8.x | 6.x and older |
+
+Post-V1 integrations remain out of scope here: Resque, Delayed Job, GoodJob, Sneakers, Shoryuken, Sinatra, Hanami, and deep ActiveRecord or SQL auto-instrumentation.
+
+## Dependency Alignment
+
+`debugbundle` ships as one gem in V1, so there is no multi-package version-alignment surface like an npm family rule or Maven BOM.
+
+- Pin one `debugbundle` version across your Ruby web app and worker repos when you want identical SDK behavior everywhere.
+- Keep Rack, Rails, and Sidekiq inside the supported lanes above.
+- Do not mix unsupported framework majors into examples or deployment templates.
+
+## Browser Relay
+
+Ruby backends can receive browser events at `POST /debugbundle/browser` through the relay handler.
+
+Rails applications can let the Railtie append that route automatically, or override it with:
+
+- `config.debugbundle.relay_enabled = false` to disable automatic mounting
+- `config.debugbundle.relay_path = "/debugbundle/browser"` to change the mounted path
+- `config.debugbundle.relay_allowed_origins = ["https://app.example.com"]` to pin allowed origins
+- `config.debugbundle.relay_rate_limit_per_minute = 120` to adjust per-IP rate limiting
+- `config.debugbundle.relay_rate_limit_store = Rails.cache` to share rate limiting across processes
+- `config.debugbundle.relay_handler = custom_handler` to supply a custom relay handler
+
+Rack applications can mount the same handler explicitly:
+
+```ruby
+relay_handler = DebugBundle::Relay::Handler.new(
+  project_mode: :connected,
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  endpoint: "https://api.debugbundle.com/v1/events",
+  allowed_origins: ["https://app.example.com"]
+)
+
+use DebugBundle::Rack::RelayMiddleware, handler: relay_handler
+```
+
+Relay behavior:
+
+- same-origin is the safe default when you do not set explicit allowed origins
+- use explicit allowed origins when the frontend and backend live on different hosts
+- requests must use `Content-Type: application/json`
+- request bodies are capped at 256 KB
+- per-IP rate limiting defaults to 60 requests per minute
+- browser-supplied DebugBundle credentials are stripped before delivery, preserving credential isolation
+- browser `service`, `environment`, and correlation fields are preserved unless you explicitly override them in the relay handler
+- local-only mode writes validated browser events to `.debugbundle/local/events`
+- connected durable mode writes validated browser events to `.debugbundle/local/browser-relay-spool` before forwarding to the configured endpoint
+- set `relay_durable_write: false` when you intentionally want connected forwarding without the local spool write
+- to disable the relay entirely, leave the route unmounted or set `relay_enabled = false`
+- a missing token means connected forwarding cannot succeed; treat that as a server config error and leave the route disabled until the server-side token is fixed
+
+## Remote Probes
+
+Probe buffers stay local and flush on captured exceptions by default. Paid-tier projects can also activate probes for immediate `probe_event` shipping through the polled remote config.
+
+For one-off request diagnostics, the Ruby SDK also accepts signed trigger tokens:
+
+- header: `X-DebugBundle-Probe-Trigger: dbundle_probe_...`
+- query parameter: `?_debug_probe=dbundle_probe_...`
+
+Matching probes still stay in the local ring buffer, but the triggered request also emits standalone `probe_event` records immediately when the token is valid.
+
+## Safety Defaults
 
 - SDK failures are isolated from host application failures.
 - Sensitive values are redacted before buffering or transport.
@@ -121,13 +263,69 @@ Matching probes still stay in the local ring buffer, but the triggered request a
 - `development`, `local`, and `test` environments write local event files by default.
 - Browser relay requests cannot smuggle server-side credentials.
 
+## Service Naming
+
+Use distinct service names when one DebugBundle project receives events from multiple deployables:
+
+- Browser frontend: `checkout-web`
+- Rails or Rack API: `checkout-api`
+- Sidekiq worker: `checkout-worker`
+
+The Ruby relay preserves the browser-provided service name and environment by default. Only override relay-level `service` or `environment` when you intentionally want the backend relay host to rewrite browser event identity.
+
+## Safe Startup and Status
+
+The SDK never raises host-facing exceptions because of missing config, bad transport responses, or malformed remote config payloads.
+
+- `DebugBundle.init(project_token: "")` leaves capture disabled and `DebugBundle.status` reports `:degraded`
+- `DebugBundle.init(enabled: false)` keeps the SDK as a no-op and `DebugBundle.status` reports `:disconnected`
+- `DebugBundle.last_event_at` stays `nil` until a successful flush completes
+- `DebugBundle.flush` is a no-op when the SDK has no buffered events, no transport, or is still waiting out a retry window
+
+Status meanings:
+
+- `:healthy` — idle or the last flush succeeded
+- `:degraded` — missing token or a temporary rate-limit window is preventing immediate delivery
+- `:disconnected` — the SDK is disabled or repeated transport failures exhausted the connection path
+
+The release rule here is fail-safe, not fail-open: connected mode with a missing token must never pretend capture is healthy.
+
+## First-Event Verification
+
+Use an explicit test message or exception during setup:
+
+```ruby
+require "debugbundle"
+
+DebugBundle.init(
+  project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+  service: "debugbundle-first-event",
+  environment: "staging"
+)
+
+DebugBundle.capture_message("debugbundle first-event verification", level: :error)
+DebugBundle.flush
+puts [DebugBundle.status, DebugBundle.last_event_at].inspect
+```
+
+Then confirm the event through your mock ingestion endpoint, a staging project, or the DebugBundle CLI verification flow.
+
+This repository also ships a clean-install app-driven smoke harness that validates the built gem and the published gem path:
+
+```sh
+make smoke
+make smoke-published VERSION=0.1.0
+```
+
+`make smoke` builds the gem, installs it into a fresh RubyGems home, drives a Rack request plus a browser relay batch through the public SDK surface, validates event envelope shape, and confirms the mock ingestion endpoint receives the expected service, environment, SDK metadata, and correlation fields.
+
 ## Examples
 
 - Rack app: [examples/rack_app.rb](examples/rack_app.rb)
 - Rails initializer: [examples/rails_initializer.rb](examples/rails_initializer.rb)
 - Sidekiq server setup: [examples/sidekiq_initializer.rb](examples/sidekiq_initializer.rb)
 
-## Local development
+## Development
 
 The project defaults to Docker-backed commands:
 
@@ -137,9 +335,10 @@ make test
 make compat
 make lint
 make build
+make smoke
 ```
 
-Compatibility lanes are also exercised in CI for Rails 7.0 and 7.1, Rack 2.2 and 3.x, and Sidekiq 7.x and 8.x.
+CI validates RSpec, RuboCop, compatibility lanes, gem build, and the clean-install smoke harness.
 
 ## Release
 
@@ -147,14 +346,7 @@ The repository ships a GitHub Actions release workflow at `.github/workflows/rel
 
 - Push a `v*` tag or run the workflow manually with a `version` input.
 - Configure the `RUBYGEMS_API_KEY` repository secret before enabling publish.
-- The workflow runs lint, tests, gem build, local smoke install, GitHub release creation, RubyGems publish, and a published-gem smoke install.
-
-## Supported targets
-
-- Ruby 3.1+
-- Rails 7.0+
-- Rack 2.2+
-- Sidekiq 7.x+
+- The workflow runs lint, tests, gem build, `make smoke`, RubyGems publish, and `make smoke-published VERSION=<tag>` before creating the GitHub release.
 
 ## Documentation
 

data/lib/debugbundle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DebugBundle
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/spec/fixtures/event-envelope.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://debugbundle.com/schemas/event-envelope-ruby-fixture.json",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/request_event_envelope"
+    },
+    {
+      "$ref": "#/$defs/log_event_envelope"
+    },
+    {
+      "$ref": "#/$defs/frontend_exception_envelope"
+    }
+  ],
+  "$defs": {
+    "string_map": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "service": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "environment"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "runtime": { "type": ["string", "null"], "minLength": 1 },
+        "framework": { "type": ["string", "null"], "minLength": 1 },
+        "environment": { "type": "string", "minLength": 1 }
+      }
+    },
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "request_id": { "type": ["string", "null"] },
+        "trace_id": { "type": ["string", "null"] },
+        "session_id": { "type": ["string", "null"] },
+        "user_id_hash": { "type": ["string", "null"] }
+      }
+    },
+    "envelope_base": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "event_id",
+        "event_type",
+        "sdk_name",
+        "sdk_version",
+        "service",
+        "occurred_at",
+        "correlation",
+        "payload"
+      ],
+      "properties": {
+        "schema_version": { "type": "string", "minLength": 1 },
+        "event_id": { "type": "string", "format": "uuid" },
+        "event_type": { "type": "string", "minLength": 1 },
+        "project_token": { "type": "string", "minLength": 1 },
+        "sdk_name": { "type": "string", "minLength": 1 },
+        "sdk_version": { "type": "string", "minLength": 1 },
+        "service": { "$ref": "#/$defs/service" },
+        "occurred_at": { "type": "string", "format": "date-time" },
+        "correlation": { "$ref": "#/$defs/correlation" },
+        "payload": {}
+      }
+    },
+    "request_event_envelope": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope_base" },
+        {
+          "properties": {
+            "event_type": { "const": "request_event" },
+            "payload": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["method", "path", "query", "headers", "response_status", "duration_ms"],
+              "properties": {
+                "method": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "query": { "$ref": "#/$defs/string_map" },
+                "headers": { "$ref": "#/$defs/string_map" },
+                "body": {},
+                "response_status": { "type": "integer", "minimum": 0 },
+                "duration_ms": { "type": "number", "minimum": 0 },
+                "route_template": { "type": ["string", "null"] },
+                "controller": { "type": ["string", "null"] },
+                "action": { "type": ["string", "null"] },
+                "response_headers": { "$ref": "#/$defs/string_map" },
+                "response_body": {}
+              }
+            }
+          }
+        }
+      ]
+    },
+    "log_event_envelope": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope_base" },
+        {
+          "properties": {
+            "event_type": { "const": "log_event" },
+            "payload": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["level", "message", "attributes"],
+              "properties": {
+                "level": { "type": "string", "minLength": 1 },
+                "message": { "type": "string", "minLength": 1 },
+                "attributes": { "$ref": "#/$defs/string_map" }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "frontend_exception_envelope": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope_base" },
+        {
+          "properties": {
+            "event_type": { "const": "frontend_exception" },
+            "sdk_name": { "const": "@debugbundle/sdk-browser" },
+            "payload": {
+              "type": "object",
+              "additionalProperties": true,
+              "required": ["message"],
+              "properties": {
+                "message": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

data/spec/repository_metadata_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'repository metadata' do
+  let(:repo_root) { File.expand_path('..', __dir__) }
+
+  def read_repository_file(path)
+    File.read(File.join(repo_root, path))
+  end
+
+  it 'ships the smoke harness and wires it into workflows' do
+    %w[
+      Makefile
+      smoke/run_app_driven_smoke.rb
+      smoke/app_driven_smoke_runner.rb
+      .github/workflows/ci.yml
+      .github/workflows/release.yml
+    ].each do |relative_path|
+      expect(File).to exist(File.join(repo_root, relative_path))
+    end
+
+    makefile = read_repository_file('Makefile')
+    ci_workflow = read_repository_file('.github/workflows/ci.yml')
+    release_workflow = read_repository_file('.github/workflows/release.yml')
+
+    [
+      '.PHONY: smoke',
+      '.PHONY: smoke-published',
+      'smoke/run_app_driven_smoke.rb --source local',
+      'smoke/run_app_driven_smoke.rb --source published --version $(VERSION)'
+    ].each do |fragment|
+      expect(makefile).to include(fragment)
+    end
+
+    expect(ci_workflow).to include('make smoke')
+    expect(release_workflow).to include('make smoke')
+    expect(release_workflow).to include('make smoke-published VERSION=${RELEASE_VERSION}')
+  end
+
+  it 'documents the Ruby release documentation gates in the README' do
+    readme = read_repository_file('README.md')
+
+    [
+      '## Configuration Reference',
+      'Configuration sources and precedence:',
+      'Capture-policy fields are server-owned',
+      '## Install Examples by Mode',
+      '## Runtime and Framework Support',
+      '## Dependency Alignment',
+      '## Browser Relay',
+      '## Service Naming',
+      '## Safe Startup and Status',
+      '## First-Event Verification',
+      'make smoke',
+      'same-origin',
+      'allowed origins',
+      'rate limiting',
+      'credential isolation',
+      'missing token'
+    ].each do |fragment|
+      expect(readme).to include(fragment)
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: debugbundle
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - DebugBundle
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -71,6 +70,7 @@ files:
 - spec/client_spec.rb
 - spec/debugbundle_spec.rb
 - spec/file_transport_spec.rb
+- spec/fixtures/event-envelope.schema.json
 - spec/logger_integration_spec.rb
 - spec/rack_integration_spec.rb
 - spec/rack_middleware_spec.rb
@@ -79,6 +79,7 @@ files:
 - spec/redaction_spec.rb
 - spec/relay_spec.rb
 - spec/remote_config_spec.rb
+- spec/repository_metadata_spec.rb
 - spec/sidekiq_integration_spec.rb
 - spec/sidekiq_middleware_spec.rb
 - spec/spec_helper.rb
@@ -91,7 +92,6 @@ metadata:
   source_code_uri: https://github.com/debugbundle/debugbundle-ruby
   changelog_uri: https://github.com/debugbundle/debugbundle-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -106,8 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: DebugBundle SDK for Ruby
 test_files: []