railwatch 0.1.0

data/lib/generators/railwatch/install/install_generator.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "railwatch/secret_safety"
+
+module Railwatch
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/railwatch.rb, a Kamal post-deploy hook, the browser client, and wires the test helpers."
+
+      class_option :token, type: :string,
+                           desc: "Deprecated: token in process arguments. Prefer --prompt-token, --token-stdin, or RAILWATCH_TOKEN."
+      class_option :prompt_token, type: :boolean, default: false,
+                                  desc: "Prompt for the ingest token without echoing it."
+      class_option :token_stdin, type: :boolean, default: false,
+                                 desc: "Read the ingest token from one line on standard input."
+      class_option :url, type: :string,
+                         desc: "Ingest URL, for a self-hosted Railwatch Cloud. Defaults to https://railwatch.rebulk.com."
+      class_option :kamal_secrets, type: :boolean, default: false,
+                                   desc: "Wire RAILWATCH_TOKEN through .kamal/secrets and config/deploy.yml's `env: secret:` list."
+      class_option :doctor, type: :boolean, default: true,
+                            desc: "Run railwatch:doctor when the install finishes."
+
+      # Whichever of these exists is where `startRailwatch()` is added.
+      INERTIA_ENTRYPOINTS = %w[
+        app/frontend/entrypoints/inertia.tsx
+        app/frontend/entrypoints/inertia.ts
+        app/frontend/entrypoints/inertia.jsx
+      ].freeze
+
+      IMPORT_LINE = 'import { startRailwatch } from "@/lib/railwatch"'
+      START_CALL = "startRailwatch()"
+
+      # The name is written in three places -- .env, .kamal/secrets, and
+      # config/deploy.yml -- and each of them has to be idempotent, so it is
+      # spelled once here.
+      TOKEN_VAR = "RAILWATCH_TOKEN"
+      URL_VAR = "RAILWATCH_INGEST_URL"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/railwatch.rb"
+      end
+
+      def create_kamal_hook
+        return unless File.exist?("config/deploy.yml")
+        template "post-deploy", ".kamal/hooks/post-deploy"
+        chmod ".kamal/hooks/post-deploy", 0o755
+      end
+
+      def create_browser_client
+        return unless File.directory?("app/frontend")
+        template "railwatch.ts", "app/frontend/lib/railwatch.ts"
+      end
+
+      # Adds the import and the call to the Inertia entrypoint, so page-visit
+      # timing and Core Web Vitals report with no further editing.
+      def start_browser_client
+        return unless File.directory?("app/frontend")
+
+        path = INERTIA_ENTRYPOINTS.find { |candidate| File.exist?(candidate) }
+        return say(browser_client_instructions(INERTIA_ENTRYPOINTS.first), :yellow) unless path
+
+        contents = File.read(path)
+        return say_status(:identical, path, :blue) if contents.include?(START_CALL)
+
+        imports = contents.lines.select { |line| line.match?(/\A\s*import\s/) }
+        return say(browser_client_instructions(path), :yellow) if imports.empty?
+
+        # Anchored at \A so the injection lands after the *last* import line
+        # and can only ever match once, however many imports repeat.
+        inject_into_file path, "#{IMPORT_LINE}\n\n#{START_CALL}\n",
+                         after: /\A[\s\S]*#{Regexp.escape(imports.last)}/
+      end
+
+      # `require "railwatch/rspec"` / `"railwatch/minitest"` brings in the block
+      # matchers (have_railwatch_queries, have_railwatch_n_plus_one, ...) that turn
+      # a spec suite into a performance gate. See docs/testing.md.
+      def wire_test_helper
+        if File.exist?("spec/rails_helper.rb")
+          inject_require "spec/rails_helper.rb", 'require "railwatch/rspec"', %r{^require ["']rspec/rails["'].*\n}
+        elsif File.exist?("test/test_helper.rb")
+          inject_require "test/test_helper.rb", 'require "railwatch/minitest"', %r{^require ["']rails/test_help["'].*\n}
+        end
+      end
+
+      def mount_beacon
+        route 'mount Railwatch::Engine, at: "/railwatch"'
+      end
+
+      # A token lands in .env only when Git confirms the file is ignored.
+      # URLs are not secret and can still be written to a tracked dotenv file.
+      def write_env
+        token = resolved_token
+        if options[:token]
+          say("--token exposes #{Railwatch::SecretSafety.token_preview(options[:token])} in process arguments; " \
+              "use --prompt-token or --token-stdin next time.", :yellow)
+        end
+        vars = { TOKEN_VAR => token, URL_VAR => options[:url] }.compact
+        return if vars.empty?
+        return say(env_instructions(vars), :yellow) unless dotenv_app?
+
+        if token && !safe_dotenv_for_token?
+          say("Refusing to write #{Railwatch::SecretSafety.token_preview(token)} to .env because Git does not confirm that .env is ignored. Use Rails credentials, a secret manager, or add .env to .gitignore first.", :red)
+          vars.delete(TOKEN_VAR)
+          return if vars.empty?
+        end
+
+        existing = File.exist?(".env") ? File.read(".env") : ""
+        missing = vars.reject { |name, _| existing.match?(/^#{name}=/) }
+        return say_status(:identical, ".env", :blue) if missing.empty?
+
+        body = missing.map { |name, value| "#{name}=#{value}\n" }.join
+        if File.exist?(".env")
+          append_to_file ".env", (existing.end_with?("\n") || existing.empty? ? body : "\n#{body}")
+        else
+          create_file ".env", body
+        end
+      end
+
+      # Kamal reads .kamal/secrets with shell expansion and passes only the
+      # names listed under `env: secret:` into the container, so the token
+      # needs both halves to reach the app.
+      def configure_kamal_secrets
+        return unless options[:kamal_secrets]
+        return say("--kamal-secrets: no .kamal/secrets found; run `bin/kamal init` first.", :yellow) unless File.exist?(".kamal/secrets")
+
+        secrets = File.read(".kamal/secrets")
+        if secrets.match?(/^#{TOKEN_VAR}=/)
+          say_status(:identical, ".kamal/secrets", :blue)
+        else
+          append_to_file ".kamal/secrets", "#{secrets.end_with?("\n") ? "" : "\n"}#{TOKEN_VAR}=$#{TOKEN_VAR}\n"
+        end
+
+        return say("--kamal-secrets: no config/deploy.yml found; add #{TOKEN_VAR} under `env: secret:` yourself.", :yellow) unless File.exist?("config/deploy.yml")
+
+        deploy = File.read("config/deploy.yml")
+        updated = self.class.deploy_yml_with_secret(deploy)
+        return say_status(:identical, "config/deploy.yml", :blue) if updated == deploy
+
+        create_file "config/deploy.yml", updated, force: true
+      end
+
+      def show_next_steps
+        say <<~STEPS, :green
+
+          Next steps
+            1. Set #{TOKEN_VAR}. With Kamal, add it to .kamal/secrets:
+                 #{TOKEN_VAR}=$#{TOKEN_VAR}
+               and list it under `env: secret:` in config/deploy.yml (or re-run
+               this generator with --kamal-secrets). Otherwise put it in
+               credentials and read it in the initializer:
+                 c.token = Rails.application.credentials.dig(:railwatch, :token)
+               Self-hosting? Set #{URL_VAR} too.
+               No token yet?  bin/rails railwatch:token
+            2. Verify the install:  bin/rails railwatch:doctor
+            3. Connect your AI assistant:  bin/rails railwatch:mcp
+            4. Gate performance in CI: see docs/testing.md.
+        STEPS
+      end
+
+      # Runs the same checklist the developer would run next, in this
+      # process. Railwatch's configuration was read at boot, so a token this
+      # run just wrote to .env is not visible until the app restarts -- the
+      # note below says so rather than letting a ✗ look like a broken install.
+      def run_doctor
+        return unless options[:doctor]
+        return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+        say "\nbin/rails railwatch:doctor", :green
+        require "rake"
+        Rails.application.load_tasks unless Rake::Task.task_defined?("railwatch:doctor")
+        Rake::Task["railwatch:doctor"].reenable
+        Rake::Task["railwatch:doctor"].invoke
+      rescue SystemExit
+        say "\nFix the ✗ lines above and re-run `bin/rails railwatch:doctor`. " \
+            "Values added to .env or credentials just now are only picked up after a restart.", :yellow
+      rescue StandardError => e
+        say "\nCould not run railwatch:doctor here (#{e.class}: #{e.message}). Run `bin/rails railwatch:doctor` yourself.", :yellow
+      end
+
+      # Adds RAILWATCH_TOKEN to config/deploy.yml's `env: secret:` list as a
+      # targeted text insertion. A YAML round-trip would be shorter and would
+      # throw away every comment in the file, which is most of what a Kamal
+      # deploy.yml is. Returns the contents unchanged when it is already
+      # listed.
+      def self.deploy_yml_with_secret(contents, name = TOKEN_VAR)
+        lines = contents.lines
+        env_start = lines.index { |line| line.match?(/\Aenv:\s*(#.*)?$/) }
+        return "#{contents.sub(/\n*\z/, "\n")}\nenv:\n  secret:\n    - #{name}\n" unless env_start
+
+        env_end = block_end(lines, env_start)
+        return contents if lines[env_start...env_end].any? { |line| line.match?(/\A\s*-\s*#{name}\s*\z/) }
+
+        secret_start = (env_start + 1...env_end).find { |i| lines[i].match?(/\A\s+secret:\s*(#.*)?$/) }
+        return insert_lines(lines, env_start + 1, "  secret:\n    - #{name}\n") unless secret_start
+
+        insert_lines(lines, block_end(lines, secret_start), "    - #{name}\n")
+      end
+
+      # Index of the first line after the block opened at `start`: the next
+      # line indented no more deeply than it, ignoring blanks and comments,
+      # then backed up over any trailing blank lines so an insertion lands
+      # inside the block rather than after the gap below it.
+      def self.block_end(lines, start)
+        indent = lines[start][/\A */].length
+        stop = ((start + 1)...lines.length).find { |i|
+          line = lines[i]
+          next false if line.strip.empty? || line.strip.start_with?("#")
+          line[/\A */].length <= indent
+        } || lines.length
+        stop -= 1 while stop > start + 1 && lines[stop - 1].strip.empty?
+        stop
+      end
+
+      def self.insert_lines(lines, index, text)
+        (lines[0...index] + [ text ] + lines[index..]).join
+      end
+
+      private_class_method :block_end, :insert_lines
+
+      private
+
+      def resolved_token
+        @resolved_token ||= begin
+          value = if options[:prompt_token]
+            ask("Railwatch ingest token (input hidden):", echo: false)
+          elsif options[:token_stdin]
+            $stdin.gets
+          elsif options[:token]
+            options[:token]
+          elsif !ENV[TOKEN_VAR].to_s.empty?
+            ENV[TOKEN_VAR]
+          end
+          value = value.to_s.strip
+          value unless value.empty?
+        end
+      end
+
+      def safe_dotenv_for_token?
+        !Railwatch::SecretSafety.git_tracked?(".env") && Railwatch::SecretSafety.git_ignored?(".env")
+      end
+
+      # dotenv is the only place the generator will write a token: an app
+      # that keeps its environment anywhere else gets told what to paste.
+      def dotenv_app?
+        File.exist?(".env") || (File.exist?("Gemfile") && File.read("Gemfile").match?(/^\s*gem ["']dotenv/))
+      end
+
+      def env_instructions(vars)
+        lines = vars.map do |name, value|
+          if name == TOKEN_VAR
+            "  #{name}=#{Railwatch::SecretSafety.token_preview(value)} (value hidden)"
+          else
+            "  #{name}=#{value}"
+          end
+        end
+        "Set these where this app reads its environment (.kamal/secrets, credentials, or your PaaS config). " \
+          "The token value is never printed:\n#{lines.join("\n")}"
+      end
+
+      def browser_client_instructions(path)
+        "Add these two lines to #{path} to report Inertia visits and Core Web Vitals:\n" \
+          "  #{IMPORT_LINE}\n  #{START_CALL}"
+      end
+
+      # inject_into_file on its own would append a second copy on a re-run --
+      # Thor only skips when the replacement is already byte-identical in
+      # place, and the anchor is not.
+      def inject_require(path, line, anchor)
+        contents = File.read(path)
+        return say_status(:identical, path, :blue) if contents.include?(line)
+        return say("Add `#{line}` to #{path} to get the Railwatch test matchers.", :yellow) unless contents.match?(anchor)
+
+        inject_into_file path, "#{line}\n", after: anchor
+      end
+    end
+  end
+end

data/lib/generators/railwatch/install/templates/initializer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Railwatch: first-class monitoring for Rails. Every option here can also be
+# set by the RAILWATCH_* env var named in the comment.
+Railwatch.configure do |c|
+  # c.token = ENV["RAILWATCH_TOKEN"]                    # RAILWATCH_TOKEN (required)
+  # c.ingest_url = "https://railwatch.rebulk.com"     # RAILWATCH_INGEST_URL
+  # c.deploy = "release-name"                       # RAILWATCH_DEPLOY; platform/Git auto-detected
+  # c.detect_deploy = false                         # RAILWATCH_DETECT_DEPLOY; default true
+
+  # Sampling is decided once per execution; a sampled-in request ships its
+  # whole tree of queries, cache events, jobs, mail, and logs.
+  # c.sample = { requests: 1.0, jobs: 1.0, commands: 1.0, scheduled_tasks: 1.0, channels: 1.0, exceptions: 1.0 }
+
+  # Drop whole record types: :queries, :cache_events, :mail, :broadcasts,
+  # :notifications, :outgoing_requests, :storage_ops, :view_renders, :logs, :transactions
+  # c.ignore = []
+
+  # Default vendor rake tasks (db:migrate, assets:precompile, ...) and default
+  # vendor cache-key prefixes (rack::attack, flipper, ...) are excluded unless
+  # you opt back in.
+  # c.capture_default_vendor_commands = false    # RAILWATCH_CAPTURE_DEFAULT_VENDOR_COMMANDS
+  # c.capture_default_vendor_cache_keys = false  # RAILWATCH_CAPTURE_DEFAULT_VENDOR_CACHE_KEYS
+
+  # c.log_level = :info
+  # c.buffer_bytes = 16 * 1024 * 1024   # reporter queue memory ceiling
+  # c.execution_buffer_bytes = 8 * 1024 * 1024
+  # c.batch_bytes = 8 * 1024 * 1024     # uncompressed NDJSON per request
+  # c.backpressure = true               # adapt sampling under buffer/ingest pressure
+  # c.backpressure_high_water = 0.8     # fraction of either buffer ceiling
+  # c.capture_request_payload = false   # only captured for requests that raised, always redacted
+  # Retried job errors are usually expected, so they are not captured by
+  # default; enabling this can flood the issues list when retries are common.
+  # c.capture_job_retry_errors = false  # RAILWATCH_CAPTURE_JOB_RETRY_ERRORS
+  # c.redact_headers += %w[X-Api-Key]
+  # c.redact_params  += %w[ssn]         # merged with Rails.application.config.filter_parameters
+  # c.ignored_request_paths += ["/internal/health"] # /up and /railwatch/beacon are ignored by default
+
+  # How the current user is described. Default reads Current.user then Warden.
+  # c.user { |user| { id: user.id, name: user.name, email: user.email } }
+end
+
+# A trailing "*" matches as a prefix; a string starting with "^" (or another
+# regex metacharacter) is compiled as a Regexp; anything else must match the
+# cache key exactly.
+# Railwatch.reject_cache_keys %w[session: rack::attack* ^feature_flag_\d+$]
+# Railwatch.reject_outgoing_requests { |r| r[:host] == "127.0.0.1" }
+# Railwatch.redact_queries { |q| q[:sql] = q[:sql].gsub(/email = '[^']+'/, "email = '?'") }
+# Railwatch.before_ingest { |batch| batch.size < 10_000 }   # return false to drop a batch
+
+# Called whenever Railwatch rescues one of its own internal errors (a
+# subscriber raising, or delivery failing after its retry), instead of only
+# logging to Railwatch.debug.
+# Railwatch.on_unrecoverable { |error| Rails.error.report(error, handled: true) }

data/lib/generators/railwatch/install/templates/post-deploy

@@ -0,0 +1,98 @@
+#!/bin/sh
+# Kamal post-deploy hook: records the deploy in Railwatch so charts and issues
+# get a deploy marker, regressions are attributed to a version, and the
+# platform can show a diff of the commits that shipped.
+#
+# This runs on the deployer machine, which -- unlike the app containers -- has
+# both the git history and the KAMAL_* environment
+# (https://kamal-deploy.org/docs/hooks/overview/), so it POSTs straight to the
+# ingest host instead of shelling into a container. Never fails a deploy.
+set -e
+[ -z "$RAILWATCH_TOKEN" ] && exit 0
+
+# Optional: .kamal/hooks/post-deploy --sourcemaps, or set
+# RAILWATCH_SOURCEMAPS=true. Requires the build artifacts on the deployer.
+# Prefer uploading in CI before publishing the image. Deletion is opt-in
+# with RAILWATCH_SOURCEMAPS_DELETE=true and happens only after acknowledgment.
+if [ "${1:-}" = "--sourcemaps" ] || [ "${RAILWATCH_SOURCEMAPS:-}" = "true" ]; then
+  RAILWATCH_DEPLOY="$KAMAL_VERSION" bin/rails railwatch:sourcemaps || echo "Railwatch source map upload failed" >&2
+fi
+
+if ! command -v curl >/dev/null 2>&1 || ! command -v ruby >/dev/null 2>&1 || [ -z "$RAILWATCH_INGEST_URL" ]; then
+  # Fall back to the rake task inside the deployed container. It records the
+  # same deploy minus the commit list, which a container has no git history
+  # to build.
+  bin/kamal app exec --primary --reuse "bin/rails railwatch:deploy[$KAMAL_VERSION]" || true
+  exit 0
+fi
+
+INGEST="${RAILWATCH_INGEST_URL%/}"
+
+case "$INGEST" in
+  https://*|http://localhost|http://localhost:*|http://127.0.0.1|http://127.0.0.1:*|http://\[::1\]|http://\[::1\]:*) ;;
+  http://*)
+    if [ "${RAILWATCH_ALLOW_HTTP:-}" != "true" ]; then
+      echo "Railwatch deploy marker skipped: plain HTTP ingest requires RAILWATCH_ALLOW_HTTP=true" >&2
+      exit 0
+    fi
+    ;;
+esac
+
+post() {
+  curl -sS -m 10 -X POST "$1" \
+    -H "Authorization: Bearer $RAILWATCH_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "$2" >/dev/null 2>&1 || true
+}
+
+git_log() {
+  if [ -d .git ] && command -v git >/dev/null 2>&1; then
+    git log -n 50 --format='%H%x1f%an%x1f%s%x1f%cI' 2>/dev/null || true
+  fi
+}
+
+# Set RAILWATCH_DEPLOY_URL to link the marker at a CI run or a release page.
+DEPLOY_BODY=$(git_log | ruby -rjson -e '
+  commits = $stdin.read.split("\n").reject(&:empty?).map do |line|
+    sha, author, message, at = line.split("\x1f")
+    { sha: sha, author: author, message: message, at: at }
+  end
+  puts JSON.generate(
+    deploy: ENV["KAMAL_VERSION"],
+    ref: ENV["KAMAL_VERSION"],
+    name: ENV["KAMAL_SERVICE_VERSION"],
+    url: ENV["RAILWATCH_DEPLOY_URL"],
+    server: ENV["KAMAL_HOSTS"].to_s.split(",").first,
+    timestamp: ENV["KAMAL_RECORDED_AT"],
+    performer: ENV["KAMAL_PERFORMER"],
+    destination: ENV["KAMAL_DESTINATION"],
+    service: ENV["KAMAL_SERVICE"],
+    commits: commits)
+') || DEPLOY_BODY=""
+
+if [ -n "$DEPLOY_BODY" ]; then
+  post "$INGEST/ingest/deploys" "$DEPLOY_BODY"
+fi
+
+# Which servers this deploy targeted, so the platform knows who should be
+# reporting. The docs name the role variable KAMAL_ROLE; KAMAL_ROLES is read
+# first because some Kamal versions set the plural.
+KAMAL_BODY=$(ruby -rjson -e '
+  list = ->(value) { value.to_s.split(",").map(&:strip).reject(&:empty?) }
+  puts JSON.generate(
+    version: ENV["KAMAL_VERSION"],
+    hosts: list.call(ENV["KAMAL_HOSTS"]),
+    roles: list.call(ENV["KAMAL_ROLES"] || ENV["KAMAL_ROLE"]),
+    performer: ENV["KAMAL_PERFORMER"],
+    destination: ENV["KAMAL_DESTINATION"],
+    service: ENV["KAMAL_SERVICE"],
+    recorded_at: ENV["KAMAL_RECORDED_AT"],
+    command: ENV["KAMAL_COMMAND"],
+    subcommand: ENV["KAMAL_SUBCOMMAND"])
+') || KAMAL_BODY=""
+
+if [ -n "$KAMAL_BODY" ]; then
+  post "$INGEST/ingest/kamal" "$KAMAL_BODY"
+fi
+
+exit 0