dialecto-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0bc3bd06a6b0829e2be97222212825426ca8b48c7fb42ca08cc384abb4995da7
+  data.tar.gz: f17efbb2e24fac304505560eb32b3abc069ca8f2d9f504cb281b9655c30eb0ec
+SHA512:
+  metadata.gz: 2b8aee37aca8a9a6a02f7ff1a55f0de8b1811dd629787ae9191daa960da6be270a33fe54d8897721f4e501bb176cfbc5e89db6d3c7c2bd3eeaab8f3b52688798
+  data.tar.gz: 144aee715796b263966af43415f615f22b1fab37c72bf64fd43c6162c9aa91f566b98605cfb9155fcc5c626fe68f3f94b3b8b7e06974ad5493e2d5f478a1149a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dialecto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# dialecto-rails
+
+Dialecto for Rails: the customer-side half of minimal-diff translation pull requests. Spec:
+`ddd-plan/engineering/spec-0023-rails-sdk.md`. MIT.
+
+Three parts, one gem:
+
+| Part | What it does |
+| --- | --- |
+| Scanner | `dialecto-rails scan` (and a GitHub Action) sends `config/locales/**/*.yml` to Dialecto from CI. |
+| Usage scan | Reads where Ruby and ERB code reads each key, so a key rename can rewrite its call sites. Off unless you ask. |
+| In-context editing | A development-only Railtie: click a string in your running app, edit it, open a pull request. |
+
+## In-context editing (development only)
+
+```ruby
+# Gemfile
+group :development do
+  gem "dialecto-rails"
+end
+```
+
+Start `rails server`; an "Edit text" button appears on every page. Dialecto finds the project from your git
+remote. The Railtie does nothing outside `development` (not in `test`, `staging` or `production`, even with the
+gem forced into the bundle), and its endpoints answer only a loopback peer. Only strings from your own
+`config/locales` are marked. Keep a key away from the editor with `config.dialecto.skip_keys = ["routes.*",
+/\.slug\z/]`; `DIALECTO_IN_CONTEXT=off` or `config.dialecto.enabled = false` switches it off. Fragment caching
+(`rails dev:cache`) serves cached text without markers.
+
+## Editing the live site
+
+The same gem can run in production, inert for visitors and on only for an editor who arrives with a signed launch
+link from Dialecto ("Edit on live site"). An edit made this way is an ordinary staged edit in Dialecto; the site
+never writes anything itself.
+
+### When to use it
+
+Live-site editing costs visitors nothing: no Dialecto script, no markers, the same bytes. It suits Rails sites,
+not only static ones.
+
+- **Do** wrap in `DialectoRails.unmarked { … }` anything that leaves the page during a marked render: a mail sent
+  while an editor's request is being handled, text you memoise or put in `Rails.cache`, translated text you write
+  to the database, Action Cable or Turbo Stream broadcasts, and job arguments. Markers are invisible characters;
+  they would be stored and sent to everyone.
+- **Know** that fragment caching is switched off for a marked request: it neither reads nor writes fragments (a
+  cold fragment rendered for an editor would be cached with markers and served to every visitor), so an editor's
+  pages render fresh and a visitor's cache is untouched.
+- **Do** keep the settings below in version control: they are public.
+- **Do** serve the site over HTTPS only, and set `origin` to exactly what the browser shows: `www` or the apex,
+  and the port. The launch cookie is `Secure`.
+- **Do** keep the server clock right (NTP): a launch link must arrive within two minutes of being minted.
+- **Don't** put a CDN or page cache in front that stores HTML and ignores cookies. Marked pages are sent
+  `Cache-Control: private, no-store` and `Vary: Cookie` (and lose their `ETag` and `Last-Modified`), but a cache
+  that disregards them defeats this: leave the site out or do not enable live mode.
+- **Don't** expect it on pages served from a cache without reaching Rails (page caching, a static export): there
+  is nothing to mark.
+- **Don't** compress responses inside the app, below Dialecto's middleware: the loader can't be added to a
+  compressed body, and editors get marked pages without the editor. Compress outside the app (the reverse proxy),
+  or put `Rack::Deflater` before the Dialecto middleware.
+- **Know** that the launch URL, token included, appears in reverse-proxy access logs (Rails filters it from its own
+  log). It is worth eight hours of seeing marked pages and no edits. A link to a static file path keeps its token in
+  the URL, because `ActionDispatch::Static` answers before the middleware. The editor needs the `Sec-Fetch-Dest`
+  header (Safari 16.4 or newer).
+
+### Setup
+
+Move the gem out of `group :development` so it is installed in production, and turn it on in
+`config/environments/production.rb` (or an initializer) with the settings from the repo's Dialecto settings page:
+
+```ruby
+config.dialecto.mode = :live
+config.dialecto.repo = "owner/name"
+config.dialecto.origin = "https://www.example.com"
+config.dialecto.public_key = "ed25519:…"
+```
+
+**How a release gets `:live`:** unset, `mode` is `:dev` in development and `:off` in every other environment, so a
+production deploy is inert until its config sets `mode = :live`. In `:live` the Railtie also needs `repo`, `origin`
+and `public_key`; without all three it stays off. `origin` is the site's own origin; it is never read from `Host` or
+`X-Forwarded-*`, which a proxy can rewrite. The middleware goes in after the session middleware.
+
+Ed25519 verification uses Ruby's OpenSSL bindings: the `openssl` gem 3.2 or later on OpenSSL 1.1.1 or later. Ruby
+3.3 and newer ship it. On Ruby 3.2, add `gem "openssl", ">= 3.2"` to the Gemfile; without it, live mode stays off and
+the log says why. `ruby -ropenssl -e 'p OpenSSL::VERSION'` shows what you have.
+
+### What happens
+
+- A `GET` with `?dialecto_edit=<token>` is verified inside your app (an Ed25519 signature under the repo's key,
+  made for this purpose only, `start_by` within two minutes, the token's origin equal to `origin`). A good one
+  becomes the `dialecto_edit` cookie (`HttpOnly; Secure; SameSite=Lax; Path=/`, ending at the token's `exp`, at
+  most eight hours), and the answer is `303` to the same URL without the parameter. The session is never touched.
+  A bad token is ignored, the parameter is still removed, and the reason (late, expired, bad signature, wrong
+  origin, wrong repo) is logged at `info`. Misconfigured live mode logs one warning at boot saying what is missing.
+- While the cookie is valid, `GET` and `HEAD` requests for a document or an iframe, and Turbo Drive visits
+  (same-origin fetches that ask for HTML), are marked, carry the overlay
+  loader, `Cache-Control: private, no-store`, `Vary: Cookie` and `X-Robots-Tag: noindex`, and Dialecto is added to
+  the page's CSP `frame-src` (only on those responses). The overlay is served from your own origin at
+  `/__dialecto/overlay.js`, never as a script from Dialecto. `POST`, fetches and JSON responses are never marked.
+  The flag lives in the rendering thread, so jobs and other threads never inherit it.
+- `POST /__dialecto/stop` clears the cookie.
+- In `:live` the development endpoints (`/__dialecto/context`, `/overrides`, `/marking`) do not exist and answer
+  404, and the development store is never loaded.
+- A visitor's request reaches your app untouched, and the session is not even read for them. The launch token is
+  filtered from Rails' request log (`filter_parameters`).
+
+A launch token that leaks is worth at most eight hours of seeing marked pages: it does not let anyone change text.
+Editing needs Dialecto's own sign-in, scoped to the repo and the site.
+
+### Refreshing the overlay copy
+
+`lib/dialecto_rails/in_context/assets/overlay.js` is a copy of Dialecto's built overlay. Maintainers build it in the
+Dialecto repository (`mix esbuild in_context`) and run `rake overlay:refresh` here. A test in the Dialecto repository
+fails when the copy differs from a fresh build.
+
+## Scanning from CI
+
+```yaml
+- uses: actions/checkout@v4
+- uses: dialecto-eu/dialecto-rails@v1
+  with:
+    project: 12                                  # the number in your project's Dialecto URL /repos/12
+    token: ${{ secrets.DIALECTO_SCAN_TOKEN }}
+```
+
+The action pins every third-party action it uses by full commit SHA (the tag stays in a comment); a release bumps
+them by looking up the latest tag with `gh api repos/<owner>/<repo>/releases/latest` and its commit SHA.
+
+Or without the action: `DIALECTO_SCAN_TOKEN=… DIALECTO_PROJECT=12 dialecto-rails scan`. It sends the files as
+committed at `HEAD`, never your working tree. `dialecto-rails doctor` checks the setup and says how to fix each
+problem.
+
+## Usage scan
+
+`DIALECTO_USAGES=on` (or `scan --usages`) adds, to the same scan, the places your Ruby, ERB and HAML code reads
+a key: `t("a.b")`, `I18n.t`, `translate`, `t!`, lazy keys (`t(".title")` in a view or controller), keys built
+from a literal prefix (`t("nav.#{key}")`), and methods that pass their argument on to `t` (wrappers). It sends a
+short anchor of the call (never a whole file) so a key rename can rewrite its call sites, and it reads committed
+code only. Slim and client-side JavaScript are not scanned: a key they name stays locked. Add your own
+translate helpers with `DIALECTO_I18N_FUNCTIONS=my_t,tt` and skip folders with `DIALECTO_USAGES_EXCLUDE`.
+
+Methods called on a constant count too (`Spree.t("foo")`, `::Spree.t`) when they are wrappers: defined with
+`def self.t`, under `class << self`, with `module_function` or `extend self`, or aliased. A method that comes from
+a gem, or adds a scope the scan can't read, is declared: `wrappers: [{call: "Spree.t", scope: "spree"}]` in
+`config.dialecto` or `DIALECTO_WRAPPERS="Spree.t=spree"`. `spree_core` and `solidus_core` in `Gemfile.lock` declare
+`Spree.t` and `Spree.translate` for you. Such a call is recorded with its absolute key but no edit point, so a
+rename of that key is refused, never half done.
+
+```
+dialecto-rails usages [--summary] [--out FILE] [--worktree]   # what the scan found, per key class
+dialecto-rails check                                          # CI after a rename: code that reads a key the catalogs no longer hold
+```
+
+`--worktree` reads the folder instead of `HEAD` (to try the scan on code you haven't committed; never use it for
+a scan you send). `--require-usages` fails a scan when the code can't be read, instead of sending the catalogs without call sites. The parse error of a file leaves
+the scan, as `could not be parsed: <200 bytes>`, never an exception message or source text.
+
+`dialecto-rails doctor` warns when `WEB_CONCURRENCY` is above 1, because the in-context editor's store is per
+process.
+
+If you only want your locale files read, Dialecto's settings page also generates a workflow that needs nothing
+installed (just `git`, `jq` and `curl`).
+
+## Settings
+
+An option in code wins over the environment, and the environment wins over the default.
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `url` | `DIALECTO_URL` | `https://app.dialecto.eu` |
+| `project` | `DIALECTO_PROJECT` | scan: required (the project's number); in-context: found from the git remote |
+| none (environment only) | `DIALECTO_SCAN_TOKEN` | none |
+| `catalog_paths` | `DIALECTO_CATALOG_PATHS` | `config/locales/**/*.yml,config/locales/**/*.yaml` |
+| `catalogs` | `DIALECTO_CATALOGS` | `config/locales` |
+| `usages` | `DIALECTO_USAGES=on` | off |
+| `require_usages` | `DIALECTO_REQUIRE_USAGES=on` | off |
+| `wrappers` | `DIALECTO_WRAPPERS` | none (the lockfile's gems add known ones) |
+| `i18n_functions` | `DIALECTO_I18N_FUNCTIONS` | none |
+| `usages_exclude` | `DIALECTO_USAGES_EXCLUDE` | none |
+| `default_branch` | `DIALECTO_DEFAULT_BRANCH` | `origin/HEAD` |
+| `enabled` | `DIALECTO_IN_CONTEXT=off` | on in development |
+| `paths` | `DIALECTO_PATHS` | every page |
+| `skip_keys` | `DIALECTO_SKIP_KEYS` | none |
+
+`DIALECTO_URL` must be `https://` (or `http://` on localhost): the scanner never sends the token over plain
+HTTP to another host unless `DIALECTO_ALLOW_INSECURE=1`.
+
+Exit codes: 0 done, 1 `check` found problems, 2 the command can't start (the message names the setting), 3
+Dialecto refused the scan and a retry can't help, 4 Dialecto or the network is unavailable (rerun; scans are
+idempotent).
+
+## Tests
+
+```
+rake test
+rake corpus[DIR]   # the usage scan over the ten pinned apps (heavy; fetch them with ddd-plan's corpus/fetch.sh)
+```

data/action.yml

@@ -0,0 +1,83 @@
+name: "Dialecto Rails scan"
+description: "Send a Rails project's config/locales files (and, when asked, where the code reads each key) to Dialecto."
+author: "Dialecto"
+
+branding:
+  icon: "upload-cloud"
+  color: "purple"
+
+inputs:
+  project:
+    description: "The project's number: the <number> in its Dialecto URL /repos/<number>."
+    required: true
+  token:
+    description: "The project's scan token, from a repository secret (Settings → Scan token in Dialecto)."
+    required: true
+  url:
+    description: "Your Dialecto's URL. Set it when you run Dialecto yourself."
+    required: false
+    default: "https://app.dialecto.eu"
+  catalog-paths:
+    description: "The project's translation file paths as on its Dialecto settings page, comma-separated."
+    required: false
+    default: "config/locales/**/*.yml,config/locales/**/*.yaml"
+  usages:
+    description: "Also send where the code reads each key (call-site anchors from Ruby and ERB files). Needed for key renames."
+    required: false
+    default: "false"
+  require-usages:
+    description: "Fail when the usage scan can't run, instead of sending the catalogs without it."
+    required: false
+    default: "false"
+  ruby-version:
+    description: "Ruby to install for the scan, independent of the app's own. Empty skips the install and uses the runner's Ruby (3.2 or newer)."
+    required: false
+    default: "3.4"
+  version:
+    description: "The dialecto-rails gem version to install."
+    required: false
+    default: "0.1.0"
+  working-directory:
+    description: "The repository root. Defaults to the workspace."
+    required: false
+    default: "."
+
+outputs:
+  scan-id:
+    description: "The scan's id in Dialecto."
+    value: ${{ steps.scan.outputs.scan-id }}
+  outcome:
+    description: "ingested, idempotent or skipped."
+    value: ${{ steps.scan.outputs.outcome }}
+  files:
+    description: "How many catalog files were sent."
+    value: ${{ steps.scan.outputs.files }}
+
+runs:
+  using: "composite"
+  steps:
+    - if: inputs.ruby-version != ''
+      uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
+      with:
+        ruby-version: ${{ inputs.ruby-version }}
+    - name: Install dialecto-rails
+      shell: bash
+      env:
+        DIALECTO_GEM_VERSION: ${{ inputs.version }}
+      run: |
+        export GEM_HOME="$RUNNER_TEMP/dialecto-rails-gems"
+        gem install dialecto-rails -v "$DIALECTO_GEM_VERSION" --no-document
+        echo "GEM_HOME=$GEM_HOME" >> "$GITHUB_ENV"
+        echo "$GEM_HOME/bin" >> "$GITHUB_PATH"
+    - name: Scan
+      id: scan
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        DIALECTO_SCAN_TOKEN: ${{ inputs.token }}
+        DIALECTO_PROJECT: ${{ inputs.project }}
+        DIALECTO_URL: ${{ inputs.url }}
+        DIALECTO_CATALOG_PATHS: ${{ inputs.catalog-paths }}
+        DIALECTO_USAGES: ${{ inputs.usages }}
+        DIALECTO_REQUIRE_USAGES: ${{ inputs.require-usages }}
+      run: dialecto-rails scan

data/exe/dialecto-rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "dialecto_rails"
+require "dialecto_rails/scan/cli"
+
+exit DialectoRails::Scan::Cli.run(ARGV)

data/lib/dialecto-rails.rb

@@ -0,0 +1 @@
+require_relative "dialecto_rails"

data/lib/dialecto_rails/config.rb

@@ -0,0 +1,206 @@
+require "uri"
+
+module DialectoRails
+  # Settings, with sdk/astro's precedence: an option wins over the environment, and the environment wins
+  # over the default. `options` is a Hash of symbols (the Railtie's `config.dialecto`, or CLI flags).
+  class Config
+    DEFAULT_URL = "https://app.dialecto.eu".freeze
+    DEFAULT_CATALOG_PATHS = ["config/locales/**/*.yml", "config/locales/**/*.yaml"].freeze
+    DEFAULT_CATALOGS = "config/locales".freeze
+    OFF = %w[off false 0 no].freeze
+    ON = %w[on true 1 yes].freeze
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 [::1] ::1].freeze
+
+    attr_reader :options, :env
+
+    def initialize(options = {}, env = ENV)
+      @options = options.to_h.transform_keys(&:to_sym)
+      @env = env
+    end
+
+    def url
+      text(:url, "DIALECTO_URL")&.sub(%r{/+\z}, "") || DEFAULT_URL
+    end
+
+    def project = text(:project, "DIALECTO_PROJECT")
+
+    # The token is never an option: it lives in the environment (a CI secret), not in a file.
+    def scan_token = blank_to_nil(env["DIALECTO_SCAN_TOKEN"])
+
+    def catalog_paths = list(:catalog_paths, "DIALECTO_CATALOG_PATHS") || DEFAULT_CATALOG_PATHS
+
+    def catalogs = text(:catalogs, "DIALECTO_CATALOGS") || DEFAULT_CATALOGS
+
+    def source_locale = text(:source_locale, "DIALECTO_SOURCE_LOCALE")
+
+    def usages_exclude = list(:usages_exclude, "DIALECTO_USAGES_EXCLUDE") || []
+
+    def i18n_functions = list(:i18n_functions, "DIALECTO_I18N_FUNCTIONS") || []
+
+    # Translate methods called on a constant that the scan can't read, as `[{call: "Spree.t", scope: "spree"}]`.
+    # From the environment: `DIALECTO_WRAPPERS="Spree.t=spree,Admin::I18n.tr"` (a scope after `=`, optional).
+    def wrappers
+      configured = option(:wrappers)
+      return Array(configured).map { |entry| entry.is_a?(Hash) ? entry : {call: entry.to_s} } if configured
+
+      (list(:wrappers, "DIALECTO_WRAPPERS") || []).map do |item|
+        call, scope = item.split("=", 2)
+        {call: call, scope: scope}
+      end
+    end
+
+    def default_branch = text(:default_branch, "DIALECTO_DEFAULT_BRANCH")
+
+    def paths = list(:paths, "DIALECTO_PATHS")
+
+    # Strings (`*` is a wildcard) or, from Ruby config, Regexps; the environment holds strings only.
+    def skip_keys
+      configured = option(:skip_keys)
+      if configured.is_a?(Array) && !configured.empty?
+        return configured.map { |item| item.is_a?(Regexp) ? item : item.to_s.strip }.reject { |item| item == "" }
+      end
+
+      list(:skip_keys, "DIALECTO_SKIP_KEYS") || []
+    end
+
+    def usages? = flag(:usages, "DIALECTO_USAGES", default: false)
+
+    def require_usages? = flag(:require_usages, "DIALECTO_REQUIRE_USAGES", default: false)
+
+    def enabled? = flag(:enabled, "DIALECTO_IN_CONTEXT", default: true)
+
+    MODES = %i[dev live off].freeze
+
+    # `:dev`, `:live` or `:off` (spec-0025 §4). `default` is what an unset mode means: the Railtie passes
+    # `:dev` in development and `:off` everywhere else. Options only: the live settings are public and live in
+    # the app's config.
+    def mode(default = :off)
+      value = option(:mode).to_s.strip.downcase.to_sym
+      MODES.include?(value) ? value : default
+    end
+
+    # "owner/name": the Dialecto repo editors work on.
+    def repo = text(:repo, nil)
+
+    # The site's own origin, normalised like Dialecto stores it, or nil if unset or not a web URL. Never read
+    # from a request header, which a proxy can rewrite.
+    def origin = self.class.normalize_origin(option(:origin))
+
+    # The repo's `ed25519:` key as 32 raw bytes, or nil.
+    def public_key
+      value = option(:public_key).to_s.strip
+      return nil unless value.start_with?("ed25519:")
+
+      bytes = value.delete_prefix("ed25519:")
+      return nil unless bytes.match?(/\A[A-Za-z0-9_-]{43}\z/)
+
+      (bytes.tr("-_", "+/") + "=").unpack1("m0")
+    rescue ArgumentError
+      nil
+    end
+
+    # Live mode has everything it needs: switched on, a repo, an origin and a key.
+    def live?(default_mode = :off) = live_problems(default_mode).empty? && mode(default_mode) == :live
+
+    # Why `mode = :live` stays off: what is missing or malformed. Empty when live mode is fine or not asked for.
+    def live_problems(default_mode = :off)
+      return [] unless mode(default_mode) == :live
+
+      [
+        (!enabled? && "the add-on is switched off (enabled = false or DIALECTO_IN_CONTEXT=off)"),
+        (repo.nil? && "repo is not set"),
+        (origin.nil? && "origin is not set or is not an http(s) origin"),
+        (public_key.nil? && "public_key is not set or is not an ed25519:<base64url> key"),
+        (!Config.ed25519? && "the openssl gem is older than 3.2, which Ed25519 keys need: add gem \"openssl\", \">= 3.2\" to the Gemfile")
+      ].select { |problem| problem }
+    end
+
+    # Raw Ed25519 public keys arrived in the openssl gem 3.2; Ruby 3.2 ships 3.1.
+    def self.ed25519?
+      require "openssl"
+      ::OpenSSL::PKey.respond_to?(:new_raw_public_key)
+    end
+
+    # For tests: the clock, in Unix seconds, the launch token's times are checked against.
+    def clock = option(:clock).respond_to?(:call) ? option(:clock) : -> { Time.now.to_i }
+
+    def self.normalize_origin(url)
+      uri = URI.parse(url.to_s.strip)
+      return nil unless %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? && (1..65_535).cover?(uri.port.to_i)
+
+      host = uri.host.downcase
+      host = "[#{host.delete("[]")}]" if host.include?(":")
+      default_port = (uri.scheme == "https") ? 443 : 80
+      "#{uri.scheme}://#{host}#{":#{uri.port}" unless uri.port == default_port}"
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def allow_insecure? = flag(:allow_insecure, "DIALECTO_ALLOW_INSECURE", default: false)
+
+    def url_valid? = http_url? && (https? || loopback_host? || allow_insecure?)
+
+    def https? = uri&.scheme == "https"
+
+    def loopback_host? = uri ? LOOPBACK_HOSTS.include?(uri.host.to_s) : false
+
+    # Why the URL can't carry a token, or nil.
+    def url_problem
+      return "DIALECTO_URL isn't an http or https URL: #{url.inspect}" unless http_url?
+      return nil if url_valid?
+
+      "DIALECTO_URL is plain http on #{uri.host}. The scan token would travel unencrypted: use https, " \
+        "or set DIALECTO_ALLOW_INSECURE=1 for a Dialecto on a private network."
+    end
+
+    private
+
+    def uri
+      @uri ||= begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+
+    def http_url? = !uri.nil? && %w[http https].include?(uri.scheme) && !uri.host.to_s.empty?
+
+    def option(name)
+      options[name] if options.key?(name)
+    end
+
+    def text(name, var)
+      value = option(name)
+      value = value.to_s if value.is_a?(Integer)
+      blank_to_nil(value.is_a?(String) ? value : nil) || blank_to_nil(env[var])
+    end
+
+    def list(name, var)
+      value = option(name)
+      items =
+        case value
+        when Array then value.map(&:to_s)
+        when String then value.split(",")
+        end
+      items = env[var].to_s.split(",") if items.nil? || items.all? { |item| item.strip.empty? }
+      items = items.map(&:strip).reject(&:empty?)
+      items.empty? ? nil : items
+    end
+
+    def flag(name, var, default:)
+      value = option(name)
+      return value if value == true || value == false
+
+      raw = blank_to_nil(env[var])&.downcase
+      return false if OFF.include?(raw)
+      return true if ON.include?(raw)
+
+      default
+    end
+
+    def blank_to_nil(value)
+      value = value.to_s.strip
+      value.empty? ? nil : value
+    end
+  end
+end

data/lib/dialecto_rails/errors.rb

@@ -0,0 +1,21 @@
+module DialectoRails
+  # An expected failure: the CLI prints the message and exits with `exit_code`, never a stack trace.
+  class Error < StandardError
+    def exit_code = 2
+  end
+
+  # The command can't start: missing token or project, a bad URL, not a git repository, a limit.
+  class ConfigError < Error
+    def exit_code = 2
+  end
+
+  # The server refused and a retry can't help (401, 403, 413, 422).
+  class RefusedError < Error
+    def exit_code = 3
+  end
+
+  # Still failing after the retries: 429, 5xx, a timeout, a refused or reset connection.
+  class RetryableError < Error
+    def exit_code = 4
+  end
+end

data/lib/dialecto_rails/in_context/args.rb

@@ -0,0 +1,37 @@
+require "json"
+require_relative "marker"
+
+module DialectoRails
+  module InContext
+    # What a marker records about the lookup that produced its text, so the overlay can preview an edit
+    # exactly as I18n would render it: the interpolation values (strings, integers and booleans as they are,
+    # everything else as its `to_s`; a value that is itself a marked message is `{"$marked": clean text}`),
+    # and `__n`, `__form` for a plural lookup and `__html` for an `_html` key.
+    module Args
+      RESERVED = %i[scope default separator resolve object fallback fallback_in_progress fallback_original_locale
+        format cascade throw raise deep_interpolation exception_handler locale].freeze
+
+      module_function
+
+      def json(options, extras = {})
+        recorded = {}
+        options.each do |name, value|
+          next if RESERVED.include?(name) || value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(Proc)
+
+          recorded[name.to_s] = value(value)
+        end
+        extras.each { |name, value| recorded[name.to_s] = value }
+        JSON.generate(recorded)
+      end
+
+      def value(value)
+        case value
+        when String then Marker.marked?(value) ? {"$marked" => Marker.strip(value)} : value.to_s
+        when Integer, true, false then value
+        when nil then ""
+        else value.to_s
+        end
+      end
+    end
+  end
+end