nurse_andrea 0.2.5 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6b94793dda326f7f9733ff52b0c6186ce4d8d5ec638f939ef7f18db382890e0
-  data.tar.gz: f49b5d9bdaffc62d0752988213dfe37b8868f1ca792ebce9fc7819ead551e4a1
+  metadata.gz: bd771253f25db130adb2d9565f1cbd957419437f2469bf7c204f61762d2b1b0d
+  data.tar.gz: fb910b0a5c545a61bd9e4194e4aee7056563a56cf2fc7cf33e1197d113d9c487
 SHA512:
-  metadata.gz: c4d4f410da8ca576d2465b1e54df730ad1bfb7305537b5045e2571088c131ace035691c0dbe37a31dd9a807cfd32a770f751cbb5a85b736b45a64aa88a48f9d9
-  data.tar.gz: 8fbefdc77087c52bf2e9bbb4d7ae60a16a46bfc8dac69865180a926a76288f22ab1bba5934cfc548b762833b8d1bcaa7588a5326156d703415e18ac0ab53c0db
+  metadata.gz: 55eac3c3846e51e4707b3973bd1e1350731379a96d03cb0753338d5c79eb7ffd49ac8f35517e5d368ff2f67991d2d6934eb4fd1d521500c7a13c4d79096227e7
+  data.tar.gz: 69e5a5207e49ad08570a3ac25c842a958892e40ebc86bd39b3df2a81e4c1648ff0aa2b117494b550973db3a1f58e8db8f2acb92806729528d85b1a4b22b46434

data/CHANGELOG.md

@@ -1,3 +1,150 @@
+## [1.4.0] - 2026-05-19
+
+### Fixed — Self-filter R-14 compliance (False-Discoveries Patch)
+- `SelfFilter.host_matches?` previously matched against hard-coded
+  `SELF_INDICATORS = %w[nurseandrea nurse-andrea nurse_andrea]`. Customer
+  connections whose host / URL / database name happened to contain any
+  of those substrings were silently dropped from discovery emission —
+  a false-negative on customer telemetry that had been live since the
+  original fix shipped (vintage `da4b3e4`).
+- `host_matches?` now derives its match indicator from
+  `NurseAndrea.config.host` (strips scheme/port/path). Per environment:
+  prod → `nurseandrea.io`; staging → `staging.nurseandrea.io`;
+  development → `localhost`. Customer databases literally named
+  `nurse_andrea_*` are no longer affected.
+- `platform_self?` is unchanged. It matches the SDK's own Rails app
+  name (process-level self-identification), not user-supplied URLs,
+  so the R-14 anti-pattern does not apply there. File header
+  documents the distinction.
+
+### Cross-runtime parity (R-15(b))
+- All 4 SDKs have functional parity on the published feature surface
+  as of v1.3. See `docs/sdk/v1.4.0-feature-parity-audit.md` in the
+  monorepo for the full matrix and the methodology behind the claim.
+  Job/queue execution instrumentation outside Ruby ActiveJob is a
+  known pre-rule gap and is scheduled for a separate post-v1.4.0
+  sprint. HTTP outbound capture of customer code is **not** claimed
+  by v1.4.0 — no SDK currently implements it.
+
+## [1.3.0] - 2026-05-14
+
+### Added — Rack-compatible core (GAP-09, Sprint D D1)
+- The gem now loads cleanly in non-Rails Ruby processes (Sinatra,
+  plain Rack, background workers, CLI tools). Previously
+  `require "nurse_andrea"` raised `LoadError` outside a Rails
+  context because `job_instrumentation.rb`'s top-level
+  `require "active_support/concern"` failed without ActiveSupport
+  installed.
+- Public surface available without Rails:
+  `NurseAndrea.configure`, `NurseAndrea.config.valid?`,
+  `NurseAndrea::LogShipper.instance`,
+  `NurseAndrea::MetricsShipper.instance`,
+  `NurseAndrea::MetricsMiddleware` (Rack middleware),
+  `NurseAndrea.deploy(...)`. See the README's "Non-Rails usage"
+  section for the minimal Sinatra / Rack setup.
+- New spec at `spec/nurse_andrea/rack_compat_spec.rb` spawns a
+  subprocess with the Bundler env stripped and asserts the gem
+  loads, configures, and exposes the shippers without pulling in
+  Rails or ActiveSupport. Standing rule #12: load behavior is now
+  asserted by a spec, not by manual verification.
+
+### Internal
+- `lib/nurse_andrea.rb` now separates Rack-compatible requires
+  (unconditional) from Rails-only requires (guarded by
+  `defined?(ActiveSupport::Concern)` / `defined?(Rails::Railtie)` /
+  `defined?(Rails::Engine)`). No changes to the internal
+  implementation of any individual file — only their require's
+  load-time position.
+
+## [1.2.0] - 2026-05-14
+
+### Added
+- **`X-NurseAndrea-Timestamp` header on every outbound POST.** Set
+  to `Time.now.to_i.to_s` (unix-seconds integer) on logs, metrics,
+  and deploy. Server-side window validation (±5 minutes) lands in
+  the matching NurseAndrea Rails release; requests outside the
+  window are rejected with HTTP 401
+  `error: "timestamp_out_of_window"`.
+  This is GAP-07 Phase 2 of the replay-mitigation work — see
+  `SECURITY.md` and `docs/sdk/payload-format.md` §2.1 for the
+  threat-model rationale and Phase 3 (HMAC) roadmap.
+- Sprint B parity test extended to assert the timestamp header is
+  present and within drift on logs / metrics / deploy.
+
+### Notes
+- **Backward compatibility.** Servers running the matching Rails
+  release accept requests **without** the timestamp header (older
+  SDKs), so upgrading the SDK without coordinating the server
+  upgrade is safe. The accept-when-absent behavior goes away in
+  Phase 3.
+
+## [1.1.0] - 2026-05-14
+
+### Fixed (cross-runtime parity — wire spec at docs/sdk/payload-format.md)
+- Status endpoint regression: `GET /nurse_andrea/status` returned
+  500 since the 1.0 release because the controller's `masked_token`
+  helper referenced the pre-1.0 `config.api_key` field, which raises
+  `MigrationError` in 1.0. The endpoint now reads `config.org_token`.
+  Caught by the new Sprint A host-app CI fixture; in-the-wild
+  installs running 1.0 should upgrade to restore the health check.
+
+### Notes
+- No behavior changes in this release for Ruby host apps beyond the
+  status-endpoint fix above. Ruby was already aligned with the
+  cross-runtime payload spec (Sprint B audit confirmed Ruby
+  emits the canonical log and metric field names —
+  `occurred_at` / `source` / `payload` and `occurred_at` —
+  that the spec adopts).
+- Ruby-only optional emissions documented in
+  docs/sdk/payload-format.md and excluded from the parity contract:
+  the `User-Agent: nurse_andrea-ruby/<version>` header, per-log
+  `batch_id` for request tracing, top-level `platform` on metrics
+  (when platform detection is enabled), `component_discoveries`
+  (when service discovery is enabled), `component_metrics` (from
+  the InstrumentationSubscriber).
+
+### Added
+- `NurseAndrea::BootDiagnostics` — Sprint A D6 module that provides
+  per-cause warn messages from the Railtie when configuration is
+  incomplete. Replaces the generic "Configuration incomplete at
+  logger wrap time" warn with messages naming the specific failure
+  mode and the env var or setter to update.
+
+## [1.0.0] - 2026-05-06
+
+### Breaking
+- Replaced `api_key` / `token` / `ingest_token` with three required
+  fields: `org_token`, `workspace_slug`, `environment`. Old field
+  setters and getters now raise `NurseAndrea::MigrationError` at boot
+  with a link to the migration guide. There is no compatibility shim.
+- New required request headers: `Authorization: Bearer <org_token>`,
+  `X-NurseAndrea-Workspace: <slug>`, `X-NurseAndrea-Environment: <env>`.
+  Single-token-per-workspace auth is gone.
+- `environment` must be one of `production`, `staging`, `development`.
+  Anything else raises a `ConfigurationError` at `validate!` time.
+  `RAILS_ENV=test` auto-detects to `production` with a one-time warning.
+- `workspace_slug` is validated locally (lowercase a-z, 0-9, hyphens;
+  must start with a letter; 1-64 chars). Reserved-word enforcement
+  remains server-authoritative.
+
+### Added
+- `NurseAndrea::SlugValidator` — local format validation.
+- `NurseAndrea::EnvironmentDetector` — auto-detection from `RAILS_ENV`
+  / `RACK_ENV` with a one-time stderr warning on unsupported values.
+- `NurseAndrea::MigrationError` (descends from `ConfigurationError`).
+- Structured rejection handling: after 5 consecutive `401`/`403`/`422`/
+  `429` responses with the same error code, the SDK prints one stderr
+  warning per process lifecycle with actionable guidance keyed off the
+  server's `error` field (e.g. `invalid_org_token`, `workspace_rejected`,
+  `auto_create_disabled`, `similar_slug_exists`).
+- `X-NurseAndrea-SDK: ruby/<version>` identity header on every request.
+
+### Migration
+- See https://docs.nurseandrea.io/sdk/migration. Short version: replace
+  the single `c.token` line with `c.org_token`, `c.workspace_slug`,
+  `c.environment`. Pull `org_token` from the org settings page (was
+  `account.token`); pick a slug for each app/service.
+
 ## [0.1.7] - 2026-04-06
 
 ### Added

data/README.md

@@ -1,6 +1,12 @@
 # NurseAndrea Ruby SDK
 
-The official Ruby gem for [NurseAndrea](https://nurseandrea.com) — observability for Rails startups.
+The official Ruby gem for [NurseAndrea](https://nurseandrea.io) —
+observability for Rails startups and any plain-Ruby service. Version
+`1.3.0`.
+
+As of 1.3.0 the gem loads cleanly in non-Rails Ruby processes
+(Sinatra, plain Rack, background workers, CLI tools). See
+[Non-Rails usage](#non-rails-usage) below.
 
 ## Installation
 
@@ -17,30 +23,107 @@ bundle install
 rails generate nurse_andrea:install
 ```
 
-Set your API key:
+Set the required environment variable:
 
 ```bash
-export NURSE_ANDREA_API_KEY="your_token_from_dashboard"
+export NURSE_ANDREA_ORG_TOKEN="org_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 ```
 
 ## What it does
 
-- **Log shipping** — captures all `Rails.logger` calls and ships them to your NurseAndrea dashboard
-- **Request metrics** — measures every HTTP request (duration, status code, path) via Rack middleware
-- **Backfill** — ships the last 24h of your Rails log file on first startup
-- **Health endpoint** — mounts `/nurse_andrea/status` so the dashboard can verify your connection
+- **Log shipping** — captures `Rails.logger` calls and ships them to
+  the NurseAndrea dashboard.
+- **Request metrics** — measures every HTTP request (duration,
+  status, path) via Rack middleware.
+- **Backfill** — ships the last 24h of your Rails log file on first
+  startup.
+- **Health endpoint** — mounts `/nurse_andrea/status` so the
+  dashboard can verify the integration.
 
 ## Configuration
 
+The `rails generate nurse_andrea:install` generator drops
+`config/initializers/nurse_andrea.rb`:
+
 ```ruby
-NurseAndrea.configure do |config|
-  config.api_key        = ENV["NURSE_ANDREA_API_KEY"]
-  config.log_level      = :warn
-  config.backfill_hours = 48
-  config.enabled        = !Rails.env.test?
+NurseAndrea.configure do |c|
+  c.org_token      = ENV["NURSE_ANDREA_ORG_TOKEN"]
+  c.workspace_slug = "your-app"
+  c.environment    = ENV.fetch("RAILS_ENV", "production")
+  c.host           = ENV.fetch("NURSE_ANDREA_HOST", "https://nurseandrea.io")
+  c.enabled        = !Rails.env.test?
+  c.log_level      = :warn
 end
 ```
 
+All three of `org_token`, `workspace_slug`, and `environment` are
+required. Missing any of them silently disables the SDK and emits a
+`stderr` warn — see [SECURITY.md](../../SECURITY.md) for the
+misconfiguration contract.
+
+## Non-Rails usage
+
+The gem's core ships logs and metrics through plain Ruby — Rails is
+only needed for the Rails-specific glue listed below. Sinatra,
+plain-Rack, background workers, and non-web services can `require`
+the gem directly:
+
+```ruby
+require "nurse_andrea"
+
+NurseAndrea.configure do |c|
+  c.org_token      = ENV["NURSE_ANDREA_ORG_TOKEN"]
+  c.workspace_slug = "my-service"
+  c.environment    = ENV.fetch("RACK_ENV", "production")
+end
+
+# Ship logs directly:
+NurseAndrea::LogShipper.instance.enqueue(
+  level:     "info",
+  message:   "hello from sinatra",
+  timestamp: Time.now.utc.iso8601(3)
+)
+
+# Or wrap the HTTP-metrics middleware in a Rack app:
+use NurseAndrea::MetricsMiddleware
+```
+
+### What's available without Rails
+
+- `NurseAndrea.configure`, `NurseAndrea.config`,
+  `NurseAndrea.config.valid?`
+- `NurseAndrea::LogShipper.instance` — direct log ingest API
+- `NurseAndrea::MetricsShipper.instance` — direct metric ingest API
+- `NurseAndrea::MetricsMiddleware` — Rack middleware for HTTP
+  request duration / status / path
+- `NurseAndrea.deploy(...)` — deploy markers
+- Platform / managed-service / continuous discovery scanners
+
+### What requires Rails
+
+These features auto-wire when Rails is present and are inactive in
+non-Rails processes. If you need any of them, install in a Rails
+app instead:
+
+- `NurseAndrea::Engine` mount at `/nurse_andrea/status` — the
+  dashboard's health-check endpoint
+- `NurseAndrea::Railtie` boot hooks — automatic
+  `Rails.logger` wrapping, middleware installation,
+  initializer-time validation, per-cause boot warnings
+- `rails generate nurse_andrea:install` — drops the initializer
+- `ActiveSupport::Notifications`-based instrumentation
+  (`sql.active_record`, `cache_*`, `perform.active_job`,
+  `deliver.action_mailer`)
+- `NurseAndrea::JobInstrumentation` — `around_perform` hook for
+  ActiveJob jobs
+- Automatic backfill of the Rails log file on first boot
+
+## Migration from 0.x
+
+`api_key`, `token`, and `ingest_token` are no longer supported.
+Setting any of them raises `NurseAndrea::MigrationError` at boot.
+See [`docs/sdk/migration.md`](../../docs/sdk/migration.md).
+
 ## Version history
 
 See [CHANGELOG.md](CHANGELOG.md).

data/app/controllers/nurse_andrea/status_controller.rb

@@ -18,7 +18,11 @@ module NurseAndrea
     private
 
     def masked_token
-      token = NurseAndrea.config.api_key.to_s
+      # SDK Sprint A D3 (GAP-03 surfaced this) — pre-1.0 referenced
+      # config.api_key, which now raises MigrationError. The 1.0
+      # field is org_token; the status controller was missed during
+      # the auth-contract rewrite. Host-app fixture smoke caught it.
+      token = NurseAndrea.config.org_token.to_s
       return "not_configured" if token.empty?
       "#{token[0..7]}..."
     end

data/lib/generators/nurse_andrea/install/templates/nurse_andrea.rb.tt

@@ -1,16 +1,24 @@
 # NurseAndrea Observability SDK
 # Docs: https://nurseandrea.io/docs
 #
-# Environment variables required:
-#   NURSE_ANDREA_TOKEN — your account ingest token (from nurseandrea.io/dashboard/settings)
-#   NURSE_ANDREA_HOST  — NurseAndrea endpoint (default: https://nurseandrea.io)
-#                        Set to http://localhost:4500 for local development
-#                        Set to https://staging.nurseandrea.io for staging
+# Required environment variable:
+#   NURSE_ANDREA_ORG_TOKEN — your organization's ingest token
+#                            (from nurseandrea.io/dashboard/settings)
+# Optional environment variables:
+#   NURSE_ANDREA_HOST      — NurseAndrea endpoint (default: https://nurseandrea.io)
+#                            Set to http://localhost:4500 for local development
+#                            Set to https://staging.nurseandrea.io for staging
+#
+# workspace_slug identifies which workspace within your org receives ingest.
+# Lowercase letters, numbers, hyphens; starts with a letter; 1-64 chars.
+# A new slug auto-creates as a pending workspace on first ingest.
 
 NurseAndrea.configure do |c|
-  c.token        = ENV["NURSE_ANDREA_TOKEN"]
-  c.host         = ENV.fetch("NURSE_ANDREA_HOST", "https://nurseandrea.io")
-  c.service_name = ENV.fetch("NURSE_ANDREA_SERVICE_NAME", "<%= app_name %>")
-  c.enabled      = !Rails.env.test?
-  c.log_level    = :warn  # Set to :debug to see all intercepted logs
+  c.org_token      = ENV["NURSE_ANDREA_ORG_TOKEN"]
+  c.workspace_slug = "<%= app_name %>"
+  c.environment    = ENV.fetch("RAILS_ENV", "production")
+  c.host           = ENV.fetch("NURSE_ANDREA_HOST", "https://nurseandrea.io")
+  c.service_name   = ENV.fetch("NURSE_ANDREA_SERVICE_NAME", "<%= app_name %>")
+  c.enabled        = !Rails.env.test?
+  c.log_level      = :warn  # Set to :debug to see all intercepted logs
 end

data/lib/nurse_andrea/boot_diagnostics.rb

@@ -0,0 +1,47 @@
+module NurseAndrea
+  # Sprint A D6 (GAP-10) — per-failure-mode boot messages. Lives
+  # outside the Railtie so the message map can be tested without
+  # booting Rails. The Railtie calls .message_for(config) from its
+  # warn-and-disable branches; the unit specs target this module
+  # directly.
+  #
+  # Pre-Sprint-A the Railtie emitted a single generic warn
+  # ("Configuration incomplete at logger wrap time — monitoring
+  # disabled. Ensure NurseAndrea.configure is called in
+  # config/initializers/nurse_andrea.rb with a valid token.")
+  # regardless of which field was missing. Operators had to grep
+  # the codebase to know what to fix. The per-cause messages below
+  # name the exact failure mode and the env var or setter to update.
+  module BootDiagnostics
+    GUIDANCE = {
+      missing_org_token:
+        "[NurseAndrea] org_token is not set — monitoring disabled. " \
+        "Set NURSE_ANDREA_ORG_TOKEN in your environment.",
+      missing_workspace_slug:
+        "[NurseAndrea] workspace_slug is not set — monitoring disabled. " \
+        "Set c.workspace_slug in config/initializers/nurse_andrea.rb.",
+      missing_environment:
+        "[NurseAndrea] environment is not set — monitoring disabled. " \
+        "Set c.environment in config/initializers/nurse_andrea.rb " \
+        "(production / staging / development).",
+      invalid_environment:
+        "[NurseAndrea] environment is invalid — monitoring disabled. " \
+        "Must be one of: production, staging, development.",
+      invalid_workspace_slug:
+        "[NurseAndrea] workspace_slug is invalid — monitoring disabled. " \
+        "Slug must be lowercase letters, numbers, and hyphens; " \
+        "start with a letter; 1-64 characters.",
+      missing_host:
+        "[NurseAndrea] host is not set — monitoring disabled. " \
+        "Set NURSE_ANDREA_HOST or leave the default (https://nurseandrea.io)."
+    }.freeze
+
+    DISABLED =
+      "[NurseAndrea] monitoring is disabled (c.enabled = false).".freeze
+
+    def self.message_for(config)
+      return DISABLED unless config.enabled?
+      GUIDANCE[config.validation_diagnostic]
+    end
+  end
+end

data/lib/nurse_andrea/configuration.rb

@@ -1,6 +1,14 @@
 module NurseAndrea
   class Configuration
-    attr_accessor :api_key, :host, :timeout, :log_level, :batch_size,
+    SUPPORTED_ENVIRONMENTS = EnvironmentDetector::SUPPORTED
+
+    MIGRATION_MESSAGE =
+      "%<field>s is no longer supported in NurseAndrea SDK 1.0. " \
+      "Migrate to org_token + workspace_slug + environment. " \
+      "See https://docs.nurseandrea.io/sdk/migration"
+
+    attr_accessor :org_token, :workspace_slug, :environment, :host,
+                  :timeout, :log_level, :batch_size,
                   :flush_interval, :backfill_hours, :log_file_path,
                   :enabled, :debug, :service_name,
                   :sdk_version, :sdk_language,
@@ -14,6 +22,7 @@ module NurseAndrea
 
     def initialize
       @host           = DEFAULT_HOST
+      @environment    = EnvironmentDetector.detect
       @timeout        = 5
       @log_level      = :debug
       @batch_size     = 100
@@ -35,13 +44,19 @@ module NurseAndrea
       @service_discovery  = true
       @auto_connect       = false
       @disable_continuous_scan  = false
-      @continuous_scan_interval = 5 * 60  # seconds
+      @continuous_scan_interval = 5 * 60
     end
 
-    alias_method :token,  :api_key
-    alias_method :token=, :api_key=
+    %i[api_key token ingest_token].each do |legacy|
+      define_method(legacy) do
+        raise MigrationError, format(MIGRATION_MESSAGE, field: legacy)
+      end
+
+      define_method("#{legacy}=") do |_|
+        raise MigrationError, format(MIGRATION_MESSAGE, field: legacy)
+      end
+    end
 
-    # All endpoint URLs derived from host
     def ingest_url    = "#{normalised_host}/api/v1/ingest"
     def metrics_url   = "#{normalised_host}/api/v1/metrics"
     def traces_url    = "#{normalised_host}/api/v1/traces"
@@ -57,29 +72,75 @@ module NurseAndrea
     end
 
     def valid?
-      !api_key.nil? && !api_key.to_s.strip.empty? && !host.nil?
+      validation_diagnostic.nil?
+    end
+
+    # Sprint A D6 (GAP-10) — returns nil when configuration is valid,
+    # otherwise returns a symbol identifying the first failure mode.
+    # The Railtie maps these symbols to operator-actionable stderr
+    # messages so a missing-org_token miss tells the operator to
+    # set the env var rather than emitting the generic
+    # "Configuration incomplete at logger wrap time" line.
+    #
+    # Order matters: most-likely-missing field first. Operators
+    # debugging from logs benefit from the first message being the
+    # most common cause.
+    def validation_diagnostic
+      return :missing_org_token      if blank?(org_token)
+      return :missing_workspace_slug if blank?(workspace_slug)
+      return :missing_environment    if blank?(environment)
+      return :invalid_environment    unless SUPPORTED_ENVIRONMENTS.include?(environment)
+      return :invalid_workspace_slug unless SlugValidator.valid?(workspace_slug)
+      return :missing_host           if host.nil?
+      nil
     end
 
     def validate!
-      unless valid?
-        raise NurseAndrea::ConfigurationError,
-          "[NurseAndrea] Configuration invalid. " \
-          "Set NURSE_ANDREA_TOKEN and NURSE_ANDREA_HOST, then call " \
-          "NurseAndrea.configure in config/initializers/nurse_andrea.rb"
+      raise_config_error("org_token is required")      if blank?(org_token)
+      raise_config_error("workspace_slug is required") if blank?(workspace_slug)
+      raise_config_error("environment is required")    if blank?(environment)
+
+      unless SUPPORTED_ENVIRONMENTS.include?(environment)
+        raise_config_error(
+          "environment must be one of #{SUPPORTED_ENVIRONMENTS.join(', ')} " \
+          "(got #{environment.inspect})"
+        )
       end
+
+      unless SlugValidator.valid?(workspace_slug)
+        raise_config_error(
+          "workspace_slug #{workspace_slug.inspect} is invalid. " \
+          "#{SlugValidator::HUMAN_READABLE_RULES}"
+        )
+      end
+
       self
     end
 
     private
 
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def raise_config_error(message)
+      raise ConfigurationError, "[NurseAndrea] #{message}"
+    end
+
     def normalised_host
       host.to_s.chomp("/")
     end
 
     def default_service_name
-      ENV["RAILWAY_SERVICE_NAME"].then { |v| v&.strip.presence } ||
-        ENV["NURSE_ANDREA_SERVICE_NAME"].then { |v| v&.strip.presence } ||
-        rails_app_name
+      first_present_env("RAILWAY_SERVICE_NAME", "NURSE_ANDREA_SERVICE_NAME") || rails_app_name
+    end
+
+    def first_present_env(*names)
+      names.each do |n|
+        v = ENV[n].to_s.strip
+        return v unless v.empty?
+      end
+      nil
     end
 
     def rails_app_name

data/lib/nurse_andrea/environment_detector.rb

@@ -0,0 +1,90 @@
+module NurseAndrea
+  # Resolves the deployment environment via a fixed precedence chain
+  # (high → low, first match wins):
+  #   1. explicit value set in SDK init (the override — most intentional)
+  #   2. hosting-platform metadata (Railway env name — deployment-tier truth)
+  #   3. process declared env (RAILS_ENV / RACK_ENV / APP_ENV — weakest)
+  #   4. default: "unknown" — NEVER masquerade as production
+  #
+  # "unknown" is a display-only value: when nothing resolves, the SDK
+  # transmits "unknown" verbatim; the server stores it; the UI shows
+  # "UNKNOWN". It is NOT an operational environment.
+  #
+  # The taxonomy is development / staging / production (local ⇒ development).
+  # Unmappable values (custom platform env names, "test", etc.) do not
+  # masquerade — they fall through the chain toward "unknown".
+  class EnvironmentDetector
+    SUPPORTED = %w[production staging development].freeze
+    UNKNOWN   = "unknown"
+    # Process-env vars consulted, in order (Ruby / Rack conventions).
+    PROCESS_VARS = %w[RAILS_ENV RACK_ENV APP_ENV].freeze
+
+    class << self
+      # The resolved environment value (string). Backward-compatible entry
+      # point used by Configuration#initialize. `explicit` is the optional
+      # tier-1 override (Configuration also supports a post-init override).
+      def detect(explicit = nil)
+        resolve(explicit).fetch(:value)
+      end
+
+      # Full resolution detail: { value:, source:, variable_name: }.
+      # `source` is which tier won (explicit/platform/process/default);
+      # `variable_name` is the env-var NAME read (never its value). Both are
+      # privacy-safe metadata for the ingest payload — see DATA_PRIVACY_POLICY.
+      def resolve(explicit = nil)
+        if (value = normalize(explicit))
+          return detail(value, "explicit", nil)
+        end
+
+        platform_env = PlatformDetector.context[:environment]
+        if (value = normalize(platform_env))
+          return detail(value, "platform", PlatformDetector.environment_variable_name)
+        end
+
+        PROCESS_VARS.each do |var|
+          raw = ENV[var]
+          next if raw.nil? || raw.empty?
+          if (value = normalize(raw))
+            return detail(value, "process", var)
+          end
+          warn_unsupported(raw, var) # present but unmappable — keep resolving
+        end
+
+        detail(UNKNOWN, "default", nil)
+      end
+
+      def reset_warning!
+        @warned = false
+      end
+
+      private
+
+      def detail(value, source, variable_name)
+        { value: value, source: source, variable_name: variable_name }
+      end
+
+      # Map a raw value onto the taxonomy, or nil if unmappable (so the
+      # chain falls through rather than masquerading).
+      def normalize(raw)
+        return nil if raw.nil? || raw.to_s.strip.empty?
+
+        case raw.to_s.strip.downcase
+        when "production", "prod"          then "production"
+        when "staging", "stage"            then "staging"
+        when "development", "dev", "local" then "development"
+        else nil
+        end
+      end
+
+      def warn_unsupported(value, var)
+        return if @warned
+
+        @warned = true
+        $stderr.puts(
+          "[NurseAndrea] #{var}='#{value}' is not a recognized environment " \
+          "(#{SUPPORTED.join('/')}); continuing resolution (may resolve to 'unknown')."
+        )
+      end
+    end
+  end
+end

data/lib/nurse_andrea/errors.rb

@@ -0,0 +1,7 @@
+module NurseAndrea
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class MigrationError < ConfigurationError; end
+end

data/lib/nurse_andrea/http_client.rb

@@ -4,35 +4,125 @@ require "json"
 
 module NurseAndrea
   class HttpClient
+    REJECTION_WARNING_THRESHOLD = 5
+    REJECTION_STATUSES          = [ 401, 403, 422, 429 ].freeze
+
+    @@consecutive_rejections = 0
+    @@warned_for_error       = nil
+    @@mutex                  = Mutex.new
+
+    class << self
+      def reset_rejection_state!
+        @@mutex.synchronize do
+          @@consecutive_rejections = 0
+          @@warned_for_error       = nil
+        end
+      end
+    end
+
     def initialize
-      @api_key = NurseAndrea.config.api_key
-      @timeout = NurseAndrea.config.timeout
+      @config = NurseAndrea.config
     end
 
     def post(url, body)
-      uri = URI.parse(url)
+      uri  = URI.parse(url)
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl      = uri.scheme == "https"
-      http.open_timeout  = @timeout
-      http.read_timeout  = @timeout
+      http.use_ssl     = uri.scheme == "https"
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
 
       request = Net::HTTP::Post.new(uri.path)
-      request["Content-Type"]  = "application/json"
-      request["Authorization"] = "Bearer #{@api_key}"
-      request["User-Agent"]    = "nurse_andrea-ruby/#{NurseAndrea::VERSION}"
+      build_headers.each { |k, v| request[k] = v }
       request.body = body.to_json
 
       response = http.request(request)
-      success = response.code.to_i.between?(200, 299)
-
-      if NurseAndrea.config.debug && !success
-        warn "[NurseAndrea] HTTP #{response.code} from #{uri}: #{response.body.to_s[0..200]}"
-      end
+      handle_response(response, uri)
 
-      success
+      response.code.to_i.between?(200, 299)
     rescue => e
-      warn "[NurseAndrea] HTTP error posting to #{url}: #{e.class}: #{e.message}" if NurseAndrea.config.debug
+      warn "[NurseAndrea] HTTP error posting to #{url}: #{e.class}: #{e.message}" if @config.debug
       false
     end
+
+    private
+
+    def build_headers
+      {
+        "Content-Type"              => "application/json",
+        "Authorization"             => "Bearer #{@config.org_token}",
+        "X-NurseAndrea-Workspace"   => @config.workspace_slug.to_s,
+        "X-NurseAndrea-Environment" => @config.environment.to_s,
+        "X-NurseAndrea-SDK"         => "#{@config.sdk_language}/#{@config.sdk_version}",
+        # Sprint C — replay-mitigation timestamp. Server validates the
+        # value is within ±5 minutes when the header is present; SDKs
+        # older than 1.2.0 don't send it and the server accepts
+        # gracefully. See docs/sdk/payload-format.md §2 + SECURITY.md.
+        "X-NurseAndrea-Timestamp"   => Time.now.to_i.to_s,
+        "User-Agent"                => "nurse_andrea-ruby/#{NurseAndrea::VERSION}"
+      }
+    end
+
+    def handle_response(response, uri)
+      status = response.code.to_i
+
+      if status.between?(200, 299)
+        @@mutex.synchronize do
+          @@consecutive_rejections = 0
+          @@warned_for_error       = nil
+        end
+        return
+      end
+
+      if @config.debug
+        warn "[NurseAndrea] HTTP #{status} from #{uri}: #{response.body.to_s[0..200]}"
+      end
+
+      return unless REJECTION_STATUSES.include?(status)
+
+      @@mutex.synchronize do
+        @@consecutive_rejections += 1
+        if @@consecutive_rejections >= REJECTION_WARNING_THRESHOLD
+          surface_rejection_warning(response, status)
+        end
+      end
+    end
+
+    def surface_rejection_warning(response, status)
+      body  = JSON.parse(response.body) rescue {}
+      error = body.is_a?(Hash) ? body["error"].to_s : ""
+      return if @@warned_for_error == error
+
+      @@warned_for_error = error
+      message = body.is_a?(Hash) ? body["message"].to_s : ""
+
+      $stderr.puts(
+        "[NurseAndrea] Ingest rejected (#{REJECTION_WARNING_THRESHOLD}+ consecutive). " \
+        "Status: #{status} Error: #{error.empty? ? '(unknown)' : error}. " \
+        "#{guidance_for(error)}#{message.empty? ? '' : " Details: #{message}"}"
+      )
+    end
+
+    def guidance_for(error)
+      case error
+      when "invalid_org_token"
+        "Check NURSE_ANDREA_ORG_TOKEN."
+      when "workspace_rejected"
+        "Restore the workspace in the dashboard or change workspace_slug."
+      when "workspace_limit_exceeded"
+        "Org has reached its workspace limit. Reject unused workspaces or upgrade plan."
+      when "auto_create_disabled"
+        "Auto-create disabled. Create the workspace explicitly in the dashboard before ingesting."
+      when "environment_not_accepted_by_this_install"
+        "Environment '#{@config.environment}' not accepted by NurseAndrea at #{@config.host}. Check NURSE_ANDREA_HOST."
+      when "invalid_workspace_slug"
+        SlugValidator::HUMAN_READABLE_RULES
+      when "similar_slug_exists"
+        "A similar slug already exists in this org. Did you mean an existing one?"
+      when "creation_rate_limit_exceeded", "rate_limited"
+        "Workspace creation rate limit hit. Existing workspaces still ingesting normally."
+      else
+        ""
+      end
+    end
   end
 end

data/lib/nurse_andrea/platform_detector.rb

@@ -18,6 +18,16 @@ module NurseAndrea
       "unknown"
     end
 
+    # The env-var NAME (never its value) that supplies the platform's
+    # environment tier, when the detected platform exposes one. Used by
+    # EnvironmentDetector to tag the resolution source. nil when the
+    # platform has no environment-name var.
+    def self.environment_variable_name
+      case detect
+      when "railway" then "RAILWAY_ENVIRONMENT"
+      end
+    end
+
     def self.context
       platform = detect
       ctx = { platform: platform }

data/lib/nurse_andrea/railtie.rb

@@ -2,6 +2,11 @@ require "rails/railtie"
 
 module NurseAndrea
   class Railtie < Rails::Railtie
+    # Sprint A D6 (GAP-10) — per-failure-mode boot messages. The
+    # message map + resolver live in NurseAndrea::BootDiagnostics so
+    # they can be unit-tested without booting Rails. The Railtie
+    # just calls into it from each warn-and-disable branch.
+
     # Runs after ALL initializers — including config/initializers/
     # This means NurseAndrea.configure works from config/initializers/ as expected
     initializer "nurse_andrea.wrap_logger", after: :load_config_initializers do
@@ -14,9 +19,7 @@ module NurseAndrea
                           "(host: #{NurseAndrea.config.host}, " \
                           "service: #{NurseAndrea.config.service_name || 'auto'})")
       else
-        warn "[NurseAndrea] Configuration incomplete at logger wrap time — " \
-             "monitoring disabled. Ensure NurseAndrea.configure is called " \
-             "in config/initializers/nurse_andrea.rb with a valid token."
+        warn NurseAndrea::BootDiagnostics.message_for(NurseAndrea.config)
       end
     end
 
@@ -25,8 +28,7 @@ module NurseAndrea
         app.middleware.use NurseAndrea::MetricsMiddleware
         Rails.logger.info("[NurseAndrea] MetricsMiddleware inserted")
       else
-        warn "[NurseAndrea] Skipping MetricsMiddleware — no token configured. " \
-             "Ensure NurseAndrea.configure is called in config/initializers/nurse_andrea.rb"
+        warn NurseAndrea::BootDiagnostics.message_for(NurseAndrea.config)
       end
     end
 

data/lib/nurse_andrea/self_filter.rb

@@ -1,13 +1,41 @@
-# Suppresses discovery emission when the SDK is loaded inside
-# NurseAndrea itself. Both the InstrumentationSubscriber (hook-based)
-# and the ManagedServiceScanner (env-based) must consult this filter
-# before adding to NurseAndrea.component_discoveries — otherwise the
-# platform's own infrastructure shows up as proposed components on
-# every workspace dashboard.
+# PRIVACY POLICY: This file derives platform-identifying values from
+# NurseAndrea.config (a user-supplied configuration). No raw env
+# values, connection strings, credentials, or tokens are stored or
+# transmitted. The configured host is the source of truth for what
+# counts as "platform infrastructure"; nothing is hard-coded except
+# the Rails-app-name pattern in platform_self?, which is a process-
+# level self-identification (the SDK detecting it's been loaded
+# inside the NurseAndrea Rails app for self-instrumentation) and
+# does not match against user-supplied URLs.
 
+# Suppresses discovery emission when the SDK is loaded inside
+# NurseAndrea itself, OR when a discovered connection target equals
+# NurseAndrea's own configured infrastructure host. Both the
+# InstrumentationSubscriber (hook-based) and the ManagedServiceScanner
+# (env-based) must consult this filter before adding to
+# NurseAndrea.component_discoveries — otherwise the platform's own
+# infrastructure shows up as proposed components on every workspace
+# dashboard.
+#
+# R-14 compliance: host_matches? derives its match indicator from
+# NurseAndrea.config.host rather than hard-coding "nurseandrea.io"
+# substring matching. This means:
+#   - prod (host=https://nurseandrea.io)        → indicator "nurseandrea.io"
+#   - staging (host=https://staging.nurseandrea.io) → indicator "staging.nurseandrea.io"
+#   - dev (host=http://localhost:4500)          → indicator "localhost"
+#   - tenant-specific (host=https://acme.example) → indicator "acme.example"
+# The hard-coded substring approach used pre-R-14 broke dev (no
+# "nurseandrea" in "localhost:4500") and would have broken any
+# future tenant-specific ingest URLs.
 module NurseAndrea
   module SelfFilter
-    SELF_INDICATORS = %w[nurseandrea nurse-andrea nurse_andrea].freeze
+    # Hard-coded fallback retained ONLY for platform_self? — that
+    # check matches the SDK's OWN Rails app name (process-level self-
+    # identification), which has no configured-URL equivalent. The
+    # R-14 anti-pattern (hard-coding customer URL substrings) does
+    # not apply here because the comparison target is the SDK's own
+    # environment, not a user-supplied URL.
+    PLATFORM_NAME_INDICATORS = %w[nurseandrea nurse-andrea nurse_andrea].freeze
 
     class << self
       def platform_self?
@@ -20,17 +48,32 @@ module NurseAndrea
       end
 
       def host_matches?(*candidates)
+        indicator = configured_host_indicator
+        return false if indicator.nil? || indicator.empty?
+
         candidates.compact.map(&:to_s).map(&:downcase).any? do |s|
-          SELF_INDICATORS.any? { |i| s.include?(i) }
+          s.include?(indicator)
         end
       end
 
       private
 
+      def configured_host_indicator
+        return nil unless NurseAndrea.respond_to?(:config)
+
+        host_url = NurseAndrea.config&.host
+        return nil if host_url.nil? || host_url.to_s.empty?
+
+        # Extract just the hostname: strip scheme, port, path.
+        host_url.to_s.downcase
+                .sub(%r{\Ahttps?://}, "")
+                .sub(%r{[:/].*\z}, "")
+      end
+
       def compute_platform_self
         return false unless defined?(Rails) && Rails.application
         app_name = Rails.application.class.module_parent_name.to_s.downcase
-        SELF_INDICATORS.any? { |i| app_name.include?(i) }
+        PLATFORM_NAME_INDICATORS.any? { |i| app_name.include?(i) }
       rescue
         false
       end

data/lib/nurse_andrea/slug_validator.rb

@@ -0,0 +1,15 @@
+module NurseAndrea
+  class SlugValidator
+    PATTERN = /\A[a-z][a-z0-9\-]{0,63}\z/
+
+    HUMAN_READABLE_RULES =
+      "Workspace slugs must be lowercase letters, numbers, or hyphens. " \
+      "Must start with a letter. 1-64 characters."
+
+    def self.valid?(slug)
+      return false if slug.nil? || slug.to_s.empty?
+
+      slug.to_s.match?(PATTERN)
+    end
+  end
+end

data/lib/nurse_andrea/version.rb

@@ -1,3 +1,3 @@
 module NurseAndrea
-  VERSION = "0.2.5"
+  VERSION = "1.4.1"
 end

data/lib/nurse_andrea.rb

@@ -1,4 +1,41 @@
+# Sprint D D1 (GAP-09) — Rack-compatible core. The requires below
+# divide into two layers:
+#
+#   1. Rack-compatible core (this block).
+#      Loads in any Ruby process — Sinatra, plain Rack, background
+#      worker, non-web service. Files in this layer reach into Rails
+#      ONLY behind `defined?(Rails)` / `defined?(ActiveSupport)`
+#      runtime guards inside methods, so requiring them in a non-
+#      Rails context succeeds and the methods short-circuit at call
+#      time.
+#
+#   2. Rails-only layer (the second block, guarded by Rails presence).
+#      Files here unconditionally require `rails/*` or
+#      `active_support/*` at the top of the file and therefore would
+#      raise LoadError outside a Rails app.
+#
+# Audit findings that drove this layout — surprises documented for
+# future maintainers:
+#
+#   * `log_interceptor`, `instrumentation_subscriber`, `query_subscriber`,
+#     `backfill`, `queue_depth_reporter`, `self_filter` all *use*
+#     Rails / ActiveSupport / SolidQueue / Sidekiq but only behind
+#     `defined?` guards inside methods. They are Rack-compatible at
+#     load time.
+#   * `metrics_middleware` is plain Rack middleware — it touches the
+#     env hash, never a Rails request object.
+#   * `job_instrumentation` is the only file in the historical
+#     unconditional list whose top-level requires (active_support/
+#     concern) actually require Rails. It moves below.
+#
+# The install generator at `lib/generators/nurse_andrea/install` is
+# auto-discovered by Rails when `rails generate` runs — it is never
+# required from this file, so it stays where it is and no guard is
+# needed here.
 require "nurse_andrea/version"
+require "nurse_andrea/errors"
+require "nurse_andrea/slug_validator"
+require "nurse_andrea/environment_detector"
 require "nurse_andrea/configuration"
 require "nurse_andrea/http_client"
 require "nurse_andrea/log_interceptor"
@@ -6,7 +43,6 @@ require "nurse_andrea/log_shipper"
 require "nurse_andrea/metrics_middleware"
 require "nurse_andrea/metrics_shipper"
 require "nurse_andrea/backfill"
-require "nurse_andrea/job_instrumentation"
 require "nurse_andrea/queue_depth_reporter"
 require "nurse_andrea/query_subscriber"
 require "nurse_andrea/sanitizer"
@@ -18,13 +54,18 @@ require "nurse_andrea/memory_sampler"
 require "nurse_andrea/deploy"
 require "nurse_andrea/self_filter"
 require "nurse_andrea/continuous_scanner"
+require "nurse_andrea/boot_diagnostics"
 
-require "nurse_andrea/railtie" if defined?(Rails::Railtie)
-require "nurse_andrea/engine"  if defined?(Rails::Engine)
+# Rails-only layer. Engine and Railtie pull in `rails/engine` /
+# `rails/railtie` at the top of their files; job_instrumentation
+# pulls in `active_support/concern`. Each guard checks for the
+# corresponding base class so the require is skipped cleanly in
+# non-Rails processes.
+require "nurse_andrea/job_instrumentation" if defined?(ActiveSupport::Concern)
+require "nurse_andrea/railtie"             if defined?(Rails::Railtie)
+require "nurse_andrea/engine"              if defined?(Rails::Engine)
 
 module NurseAndrea
-  class ConfigurationError < StandardError; end
-
   class << self
     def configure
       yield(config)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nurse_andrea
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 1.4.1
 platform: ruby
 authors:
 - Ago AI LLC
@@ -26,11 +26,14 @@ files:
 - lib/nurse_andrea.rb
 - lib/nurse_andrea/DATA_PRIVACY_POLICY.rb
 - lib/nurse_andrea/backfill.rb
+- lib/nurse_andrea/boot_diagnostics.rb
 - lib/nurse_andrea/component_telemetry.rb
 - lib/nurse_andrea/configuration.rb
 - lib/nurse_andrea/continuous_scanner.rb
 - lib/nurse_andrea/deploy.rb
 - lib/nurse_andrea/engine.rb
+- lib/nurse_andrea/environment_detector.rb
+- lib/nurse_andrea/errors.rb
 - lib/nurse_andrea/http_client.rb
 - lib/nurse_andrea/instrumentation_subscriber.rb
 - lib/nurse_andrea/job_instrumentation.rb
@@ -46,6 +49,7 @@ files:
 - lib/nurse_andrea/railtie.rb
 - lib/nurse_andrea/sanitizer.rb
 - lib/nurse_andrea/self_filter.rb
+- lib/nurse_andrea/slug_validator.rb
 - lib/nurse_andrea/version.rb
 - nurse_andrea.gemspec
 homepage: https://nurseandrea.io