liquidum 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d329e99f05c6d46b176299ca0c2feac75ae3e5aeeb4b8bea0eb472b8cc6c6390
-  data.tar.gz: b48bbd71720359afc2124fad497a4c73b3a51ec823e245cce996d733f941e511
+  metadata.gz: 7a3613df0269cd879899d9d22b5caaac10d81ed99b7cae5817111eabba181aff
+  data.tar.gz: c003a28fc817883048a004a20bc9d074543542dc2de4eeffd6f8a126452baf4c
 SHA512:
-  metadata.gz: 57b9531c2f52655fd04cf0432b3e87375facd2dab8f79d8c1d9c480f4a946d54ecf85175319b2f1433050ac85a8bb3a4d596143f9ce7cdc063fc9f60cc249c5c
-  data.tar.gz: b50bbe44304824e22b1cbc0e5bb92ffcbcfec7c2676c2b3caa5d335a3d99e9957663f3f1c58c65e3377b2ad3d40b8f0cd3e32110c2997430106131d04118d2e4
+  metadata.gz: 4631f8504116bb3c067832673e5b817ee6dd537c5a0438d360e16774023575a2a3309485560dd2825d48a2bb2dc2cdae50326aa4784dc62a9ae7594149f11bad
+  data.tar.gz: 87e44b29a116546be43cbf8b45bf65b23d6dae489e2b37dd602b50dcd4b588f845230e577a2de83f378261f99ed4ce71d7bf33f7da0ded698301d055954354f0

data/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,34 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2.7.1": {
+      "version": "2.7.1",
+      "resolved": "ghcr.io/devcontainers/features/common-utils@sha256:e76a6a8a35d1ad824daad1540725e0ec9f8ed2dc00d2850e990a9830013c7d08",
+      "integrity": "sha256:e76a6a8a35d1ad824daad1540725e0ec9f8ed2dc00d2850e990a9830013c7d08"
+    },
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "version": "2.17.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c",
+      "integrity": "sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.3",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:bd7ab48a832228f633239277552c30b353867fef2e5b037e064b4e64f0b843f2",
+      "integrity": "sha256:bd7ab48a832228f633239277552c30b353867fef2e5b037e064b4e64f0b843f2"
+    },
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "2.1.1",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:2a19d3b0b3879437637cfd292eb29fee0afcfbe6364e33db9afc4f80c5c1f956",
+      "integrity": "sha256:2a19d3b0b3879437637cfd292eb29fee0afcfbe6364e33db9afc4f80c5c1f956"
+    },
+    "ghcr.io/rails/devcontainer/features/activestorage": {
+      "version": "1.1.1",
+      "resolved": "ghcr.io/rails/devcontainer/features/activestorage@sha256:7fa8fff898ac33076ebf65631d3c6c902dc9bad87de3e5dfa645f3e2d7a35c07",
+      "integrity": "sha256:7fa8fff898ac33076ebf65631d3c6c902dc9bad87de3e5dfa645f3e2d7a35c07"
+    },
+    "ghcr.io/rails/devcontainer/features/postgres-client": {
+      "version": "1.2.0",
+      "resolved": "ghcr.io/rails/devcontainer/features/postgres-client@sha256:7e6b118646d6e0d82a9ec06e81ad1b5406f7042f0279d35fff3a7a612be7a050",
+      "integrity": "sha256:7e6b118646d6e0d82a9ec06e81ad1b5406f7042f0279d35fff3a7a612be7a050"
+    }
+  }
+}

data/.devcontainer/devcontainer.json

@@ -0,0 +1,46 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ruby-rails-postgres
+{
+    "name": "liquidum",
+    "dockerComposeFile": "docker-compose.yml",
+    "service": "app",
+    "features": {
+        "ghcr.io/devcontainers/features/node:2": {},
+        "ghcr.io/devcontainers/features/common-utils:2.7.1": {
+            "configureZshAsDefaultShell": true,
+            "installOhMyZsh": false,
+            "installOhMyZshConfig": false
+        },
+        "ghcr.io/rails/devcontainer/features/activestorage": {},
+        "ghcr.io/rails/devcontainer/features/postgres-client": {
+            "version": "18"
+        },
+        "ghcr.io/devcontainers/features/github-cli:1": {},
+        "ghcr.io/devcontainers/features/docker-in-docker:2": {
+            "moby": false
+        },
+        // Your own tools from ~/.config/de/config.json, written by bin/de
+        // initialize, see https://github.com/tdegrunt/de#your-own-tools
+        "./de-host": {}
+    },
+    "mounts": [
+        "source=/run/host-services/ssh-auth.sock,target=/ssh-agent,type=bind,consistency=cached",
+        "source=${localEnv:HOME}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,consistency=cached"
+    ],
+    "initializeCommand": "bin/de initialize",
+    // Closing the editor leaves the environment running, bin/de down stops it
+    "shutdownAction": "none",
+    "postStartCommand": ".devcontainer/postStart.sh",
+    "containerEnv": {
+        "VISUAL": "vi",
+        "SSH_AUTH_SOCK": "/ssh-agent"
+    },
+    "remoteEnv": {
+        // The repository's bin/, so `rails test` works in terminals
+        "PATH": "${containerWorkspaceFolder}/bin:${containerEnv:PATH}"
+    },
+    "customizations": {},
+    // Where docker-compose.yml mounts this checkout, see env_init in bin/de.
+    // /workspaces/liquidum links here too, but only once the container runs.
+    "workspaceFolder": "/workspaces${localWorkspaceFolder}"
+}

data/.devcontainer/docker-compose.yml

@@ -0,0 +1,102 @@
+# One compose project per checkout. The variables come from .devcontainer/.env,
+# written by bin/de up (or bin/de initialize when opened from an editor).
+name: ${COMPOSE_PROJECT_NAME:?run bin/de up to write .devcontainer/.env}
+
+x-env-labels: &env-labels
+  dev.env.name: ${ENV_NAME}
+  dev.env.kind: ${ENV_KIND}
+  dev.env.branch: ${ENV_BRANCH}
+  dev.env.path: ${ENV_PATH}
+  dev.env.gitdir: ${ENV_GIT_COMMON_DIR}
+
+services:
+  app:
+    image: ghcr.io/rails/devcontainer/images/ruby:4.0.5
+    labels: *env-labels
+
+    volumes:
+      # The checkout and the common .git directory sit at the same place
+      # relative to each other as on the host (under /workspaces), so a
+      # worktree's relative .git link resolves. /workspaces/<repo> links to
+      # the checkout.
+      - ${ENV_PATH}:${ENV_PATH_IN_CONTAINER}
+      - ${ENV_GIT_COMMON_DIR}:${ENV_GIT_COMMON_DIR_IN_CONTAINER}
+      # The global gitignore. Here, not in devcontainer.json, which drops
+      # readonly from its mounts.
+      - ${ENV_GIT_CONFIG_DIR}:/home/vscode/.config/git:ro
+
+    environment:
+      DEV_ENV_NAME: ${ENV_NAME}
+      DEV_ENV_KIND: ${ENV_KIND}
+      DB_HOST: postgres
+      REDIS_URL: redis://redis:6379/1
+      # See SELENIUM_URL in env.conf
+      SELENIUM_URL: ${SELENIUM_URL}
+      CAPYBARA_APP_HOST: ${CAPYBARA_APP_HOST}
+      # Other worktrees aren't mounted here, keep git gc from pruning them
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: gc.worktreePruneExpire
+      GIT_CONFIG_VALUE_0: never
+
+    expose:
+      - "3000"
+
+    # Keeps the container running after the process ends
+    command: ["sh", "-c", "sudo ln -sfn \"$$0\" \"$$1\" && exec sleep infinity", "${ENV_PATH_IN_CONTAINER}", "${ENV_WORKSPACE_LINK}"]
+    restart: ${ENV_RESTART:-no}
+
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      selenium:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:18
+    labels: *env-labels
+    restart: ${ENV_RESTART:-no}
+    volumes:
+      - postgres-data:/var/lib/postgresql/18/docker
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: valkey/valkey:8
+    labels: *env-labels
+    restart: ${ENV_RESTART:-no}
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  selenium:
+    image: selenium/standalone-firefox
+    labels: *env-labels
+    restart: ${ENV_RESTART:-no}
+    shm_size: 2gb
+    healthcheck:
+      test: ["CMD", "/opt/bin/check-grid.sh", "--host", "localhost", "--port", "4444"]
+      interval: 2s
+      timeout: 5s
+      retries: 60
+
+volumes:
+  postgres-data:
+    labels: *env-labels
+  redis-data:
+    labels: *env-labels
+
+networks:
+  default:
+    labels: *env-labels

data/.devcontainer/env.conf

@@ -0,0 +1,31 @@
+# Per-repository settings for bin/de, which comes from the de repository and
+# is the same everywhere.
+
+# Prefix of every environment name, and the folder the checkout appears at
+# inside the container (/workspaces/<ENV_REPO>, see devcontainer.json). Unique
+# per repository: de init --name sets it, default the repository's folder name.
+ENV_REPO=liquidum
+
+# Branches whose environments are persistent: they keep their volumes and are
+# never removed by bin/de prune. Every other branch gets an ephemeral one.
+PERSISTENT_BRANCHES=(staging develop)
+
+# Branches whose environment is named just ENV_REPO, e.g. reachable as
+# app.liquidum.orb.local. Always persistent.
+PRIMARY_BRANCHES=(main master)
+
+# Selenium the system tests drive: the environment's own container. To watch
+# a test in a browser on the Mac instead, override it for one command:
+#
+#   SELENIUM_URL=http://host.docker.internal:4444/ HEADLESS=0 bin/de exec bin/rails test:system
+SELENIUM_URL="http://selenium:4444/"
+
+# Run in the container at the end of bin/de up, from the checkout root, e.g.
+# to prepare the test database (postStart.sh prepares the development one).
+# A Rails engine runs it from the engine root, so its own migrations are
+# included.
+UP_COMMAND=(env RAILS_ENV=test bin/rails app:db:prepare)
+
+# Version of @devcontainers/cli to run through npx when `devcontainer` isn't
+# installed.
+DEVCONTAINER_CLI_VERSION=0.90.0

data/.devcontainer/postStart.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+MISE="$HOME/.local/bin/mise"
+# Trust first, activating reads mise.local.toml too
+"$MISE" trust
+eval "$("$MISE" activate bash)"
+"$MISE" install
+sudo chmod 666 /ssh-agent
+# So git over SSH, e.g. a git source in the Gemfile, doesn't stop to ask
+mkdir -p ~/.ssh
+ssh-keygen -F github.com >/dev/null 2>&1 || ssh-keyscan -t ed25519 github.com 2>/dev/null >> ~/.ssh/known_hosts
+
+[ ! -f package.json ] || "$MISE" exec -- npm install
+"$MISE" exec -- bundle install
+"$MISE" exec -- bin/rails db:prepare

data/.gitignore

@@ -9,3 +9,5 @@ test/dummy/yarn-error.log
 test/dummy/storage/
 test/dummy/tmp/
 Gemfile.lock
+.devcontainer/.env
+.devcontainer/de-host/

data/.shipkit.yml

@@ -0,0 +1,2 @@
+---
+previous_version: 1.2.1

data/.worktreeinclude

@@ -0,0 +1,2 @@
+.envrc
+mise.local.toml

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## Unreleased
+
+- Allow Liquid 5.4 and later (up to 6).
+- Drops describe their variables for editors: `Drop.variables`, the
+  `describe` DSL, and `GET /liquidum/variables` with signed roots
+  (`Liquidum::Variables`). See "Variables for editors" in the README.
+- `config.parent_controller` chooses the controller Liquidum's controllers
+  inherit from.
+- Removed `GET /liquidum/completions`; `/liquidum/variables` replaces it.

data/Gemfile

@@ -1,7 +1,11 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 # Declare your gem's dependencies in liquidum.gemspec.
 # Bundler will treat runtime dependencies like base dependencies, and
 # development dependencies will be added by default to the :development group.
 gemspec
+
+source "https://rubygems.pkg.github.com/entdec" do
+  gem "shipkit"
+end

data/README.md

@@ -10,6 +10,63 @@ Basically it's as easy as:
 Liquidum.render("{{payload.test}}", assigns: { 'payload' => { 'test' => 'blah' } })
 ```
 
+## Variables for editors
+
+Editors can offer the variables a template can use, as a picker or as
+suggestions after `{{`. Liquidum works them out from your drops: what Liquid
+can call on a drop, labelled with `human_attribute_name` in the current
+locale, typed from the model's columns, and followed through `association`
+to other drops.
+
+```ruby
+class OrderDrop < Liquidum::Drop
+  association :customer, :order_lines
+  delegate :number, :total, to: :@object
+
+  # Only for what Liquidum can't work out
+  describe :total, type: :money, hint: "Including VAT"
+  describe :portal_url, label: -> { I18n.t("orders.portal_url") }
+
+  def portal_url = …
+end
+
+OrderDrop.variables # => [#<data Liquidum::Variable name="customer", label="Customer", type="object", …>, …]
+```
+
+`describe` takes `label:`, `type:`, `hint:` (a string, or a proc to translate
+it), and `drop:` and `collection:` for a method that returns other drops. A
+drop is for the model with its name (`OrderDrop` is for `Order`); override
+`self.model` when that's not so.
+
+Mount the engine and give the editor a URL with the template's roots, signed,
+so a browser can't ask about other classes:
+
+```ruby
+mount Liquidum::Engine => "/liquidum"
+```
+
+```ruby
+variables = Liquidum::Variables.new(order: OrderDrop, portal_url: :string)
+liquidum.variables_path(roots: variables.token)
+```
+
+The editor asks for one level at a time:
+
+```
+GET /liquidum/variables?roots=…&path=order.customer
+{"path": "order.customer", "variables": [{"name": "email", "label": "Email", "type": "string", "collection": false, "children": false}, …]}
+```
+
+In a collection the path goes into its elements (`order.order_lines.product`).
+The endpoint only describes variables and never reads a record. Its
+controllers inherit from `::ApplicationController`; to choose another one:
+
+```ruby
+Liquidum.configure do |config|
+  config.parent_controller = "Admin::BaseController"
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/app/controllers/liquidum/application_controller.rb

@@ -1,5 +1,5 @@
 module Liquidum
-  class ApplicationController < ::ApplicationController
+  class ApplicationController < Liquidum.config.parent_controller.constantize
     protect_from_forgery with: :exception
   end
 end

data/app/controllers/liquidum/variables_controller.rb

@@ -0,0 +1,17 @@
+require_dependency "liquidum/application_controller"
+
+module Liquidum
+  # The variables at a path, for an editor's variable picker:
+  #
+  #   GET /liquidum/variables?roots=<Liquidum::Variables#token>&path=order.customer
+  #
+  # Only describes the variables; it never reads a record.
+  class VariablesController < ApplicationController
+    def index
+      variables = Variables.from_token(params[:roots]) or return head(:bad_request)
+      found = variables.at(params[:path]) or return head(:not_found)
+
+      render json: {path: params[:path].to_s, variables: found}
+    end
+  end
+end