plutonium 0.62.2 → 0.63.0

data/app/views/rodauth/_login_form.html.erb

@@ -34,6 +34,19 @@
       <% end %>
     </div>
     <%= render "password_visibility" %>
+    <%# Only rendered when the config enables `remember`. The box's value is
+        `remember_remember_param_value`, which is what the config's after_login hook
+        compares against. `include_hidden: false` keeps Rails' default "0" off the
+        wire when unticked - belt-and-braces next to that value comparison, but it
+        also keeps this form correct for a config using a bare presence check. %>
+    <% if rodauth.features.include?(:remember) %>
+      <div class="flex items-center space-x-2">
+        <%= form.check_box rodauth.remember_param,
+                       {id: "remember", class: "pu-checkbox", include_hidden: false},
+                       rodauth.remember_remember_param_value %>
+        <%= form.label "remember", rodauth.remember_remember_label, class: "text-sm text-[var(--pu-text)]" %>
+      </div>
+    <% end %>
   <% end %>
   <%= form.submit rodauth.login_button, class: "w-full pu-btn pu-btn-md pu-btn-primary" %>
 <% end %>

data/db/migrate/async_interactions/20260817000001_create_plutonium_async_runs.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+class CreatePlutoniumAsyncRuns < ActiveRecord::Migration[7.2]
+  def change
+    create_table :plutonium_async_runs do |t|
+      # STI discriminator — the author's Run subclass.
+      t.string :type, null: false
+      t.string :state, null: false, default: "pending" # pending | running | completed | failed
+
+      # JSON payloads are jsonb, matching plutonium_wizard_sessions: Postgres
+      # hosts get equality and GIN indexing (plain json has neither), and SQLite
+      # hosts get the type via PLUTONIUM_SQLITE_TYPE_ALIASES, which aliases
+      # jsonb -> json. Changing a column type post-release costs every host app a
+      # migration, so pick the queryable one now.
+      #
+      # The dispatching interaction's validated inputs.
+      t.jsonb :options, null: false, default: {}
+
+      # Targets. target_type is a REAL column, not JSON: the index feature
+      # queries "runs for this resource", which cannot be indexed out of a
+      # JSON array. Ids are re-resolved through the policy scope at perform time.
+      t.string :target_type
+      t.jsonb :target_ids, null: false, default: []
+
+      # Who started it, and in which tenant — the two halves of the policy
+      # context, which Plutonium authorizes on as (user, entity_scope).
+      #
+      # The initiator is ALWAYS required. There is no such thing as a run with
+      # no user to authorize as, and a nullable initiator would inevitably come
+      # to mean "unauthenticated/unscoped" — the fail-OPEN case.
+      #
+      # The scoped entity is nullable BY DESIGN: it is present only when the
+      # run was launched in an entity-scoped portal, and nil for an un-scoped
+      # one (same as plutonium_wizard_sessions.scope_type/scope_id). nil here
+      # means "no tenant", NOT "tenant unknown". Code rebuilding the policy
+      # context must handle nil explicitly rather than assume a tenant is
+      # present — this schema offers no non-null guarantee to lean on.
+      #
+      # *_id is string-typed to accommodate bigint or uuid host primary keys,
+      # matching plutonium_wizard_sessions.
+      t.string :initiator_type, null: false
+      t.string :initiator_id, null: false
+      t.string :scoped_entity_type
+      t.string :scoped_entity_id
+
+      # The third half of the policy context: WHICH policy applied.
+      #
+      # Policy lookup in a controller passes the controller's own module nesting
+      # as the namespace (ActionPolicy::Behaviours::Namespaced), which is how a
+      # portal gets its own policy — StorefrontPortal::Blogging::PostPolicy
+      # rather than Blogging::PostPolicy. A job has no controller and therefore
+      # no namespace to derive, so without this the lookup falls back to the base
+      # policy and every narrowing the portal applied is silently lost. Nullable
+      # because a top-level dispatch legitimately has no namespace; nil here
+      # means "top level", NOT "namespace unknown".
+      #
+      # Stored as the module's NAME (e.g. "StorefrontPortal"), constantized at
+      # perform time — ActionPolicy.lookup requires a Module and raises on a
+      # String.
+      t.string :authorization_namespace
+
+      # The nested-route PARENT, and the association the child hangs off it —
+      # /orgs/1/posts/5/comments dispatches with (Post#5, :comments).
+      #
+      # Both halves or neither: Policy#default_relation_scope raises on one
+      # without the other, and it is the pair that names a scope.
+      #
+      # The third input the policy authorizes on, alongside the initiator and the
+      # tenant. Without it, Policy#default_relation_scope cannot take its parent
+      # branch and falls through to entity scoping — so perform time re-derives
+      # targets under the TENANT where dispatch used the parent, a wider answer
+      # than the one the initiator was shown. It also leaves any host predicate
+      # reading +parent+ looking at nil, which refuses every target with a reason
+      # that names the wrong thing.
+      #
+      # Nullable, like scoped_entity and for the same reason: most routes are not
+      # nested. nil means "not a nested dispatch", NOT "parent unknown" — see
+      # AsyncRuns::Context#verify_subjects!, which tells those apart by the _type
+      # column exactly as it does for the tenant.
+      t.string :parent_type
+      t.string :parent_id
+      t.string :parent_association
+
+      # The policy actually resolved AT DISPATCH, e.g.
+      # "StorefrontPortal::Blogging::PostPolicy". An ASSERTION, not an input: at
+      # perform time the policy is resolved from the namespace above and then
+      # checked against this. The namespace fixes today's lookup, but a policy
+      # renamed, deleted or re-parented between enqueue and perform would resolve
+      # to something else — the same silent widening, just moved later in time.
+      # Recording what we expected turns that into a loud failure.
+      #
+      # NOT named `policy_class`: ActionPolicy's lookup chain probes
+      # `record.policy_class` before inferring from the class name, so a column
+      # of that name would make ActionPolicy.lookup(run) return this String
+      # instead of a policy — breaking authorization of run records themselves.
+      t.string :policy_class_name
+
+      # The policy PREDICATE dispatch checked, e.g. "archive?".
+      #
+      # The class above says which policy; this says which question to ask it.
+      # Without it a run re-checks only VISIBILITY (the relation scope) and not
+      # PERMISSION: an initiator whose archive? flipped to false after enqueue
+      # would still resolve every target and the work would proceed. Dispatch
+      # derives this from the action name and checks it PER RECORD — see
+      # Plutonium::Resource::Controllers::InteractiveActions#authorize_interactive_bulk_action!
+      # — and perform must reproduce exactly that.
+      #
+      # Nullable ONLY because opaque (untargeted) work has no per-record
+      # predicate to check. nil means "no per-target predicate", and for a
+      # TARGETED run that is refused rather than read as "allow everything" —
+      # the fail-open shape again.
+      t.string :policy_action
+
+      # Counts. Both nil for opaque (untargeted) work — the progress UI reads
+      # nil as "indeterminate" rather than 0%.
+      t.integer :progress_total
+      t.integer :progress_done, null: false, default: 0
+
+      # Per-target execution failures, appended as the run proceeds — hence an
+      # array default. A run may fail on some targets and still complete.
+      t.jsonb :errors_log, null: false, default: []
+
+      t.datetime :started_at
+      t.datetime :finished_at
+
+      # Set only once a job actually picks the run up (AsyncRuns::Executor#claim!)
+      # and bumped on every write that represents real progress thereafter —
+      # NOT at create time, and not the same thing as updated_at, which bumps
+      # on any write to the row. nil means "never picked up"; AsyncRuns::ReapJob
+      # falls back to created_at for that case.
+      t.datetime :last_activity_at
+
+      # Target ids already dispositioned (succeeded or failed), so a run
+      # resumed after an interruption can skip work it already did instead of
+      # either replaying it or refusing to resume at all. See AsyncRuns::Executor.
+      t.jsonb :handled_target_ids, null: false, default: []
+
+      # Rails' standard optimistic-locking column (same convention as
+      # plutonium_wizard_sessions.lock_version) — bumped by AsyncRuns::Executor#claim!
+      # on every successful claim, on top of the ordinary automatic bump every
+      # +save!+/+update!+ already gets. ReapJob's resume is a TIME heuristic, not
+      # a true lease (see AsyncRuns::ReapJob): it can hand a run to a second executor
+      # while the first is still mid-batch. Without this column that race
+      # silently double-applies AND can lose one side's progress write; with it,
+      # the superseded executor's next write raises ActiveRecord::StaleObjectError
+      # (see AsyncRuns::Executor#call), which is treated as "no longer mine" rather
+      # than a target or run failure.
+      t.integer :lock_version, null: false, default: 0
+
+      t.timestamps
+
+      t.index [:target_type, :state], name: "idx_pu_runs_on_target_and_state"
+      t.index [:initiator_type, :initiator_id], name: "idx_pu_runs_on_initiator"
+      t.index [:scoped_entity_type, :scoped_entity_id], name: "idx_pu_runs_on_scoped_entity"
+      # AsyncRuns::ReapJob's stalled scan filters on state with no target_type
+      # predicate, so it cannot use idx_pu_runs_on_target_and_state above (wrong
+      # leading column) — without this, the scan degrades to a full-table scan as
+      # completed/failed history accumulates. Low-cardinality but selective for
+      # this query: the in-progress rows are a vanishing fraction of a mature
+      # table, which is exactly the case that needs the index.
+      #
+      # state ALONE, deliberately. The scan's other predicate is
+      # COALESCE(last_activity_at, created_at) < ? (see Run.stalled) — an
+      # expression, so a trailing last_activity_at column could not be used for
+      # the range at all, and created_at is not in the index either, so it buys
+      # no index-only scan. It would be write cost for nothing.
+      t.index :state, name: "idx_pu_runs_on_state"
+    end
+  end
+end

data/docs/.vitepress/config.ts

@@ -1,8 +1,28 @@
-import { defineConfig } from "vitepress"
+import { defineConfig, createContentLoader, type SiteConfig, type HeadConfig } from "vitepress"
 import { withMermaid } from "vitepress-plugin-mermaid";
 import llmstxt from "vitepress-plugin-llms";
+import { Feed } from "feed";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 const base = "/plutonium-core/"
+// Origin + base, with no trailing slash — content-loader URLs already start with one.
+const hostname = "https://radioactive-labs.github.io/plutonium-core"
+
+// Whether the blog has anything a reader could actually open: a post that is not
+// a draft and whose date has arrived. Same rule the loader and the feed apply, so
+// the nav entry and the RSS advert never point at an empty page.
+const hasPublishedPost = fs
+  .readdirSync(fileURLToPath(new URL("../blog", import.meta.url)))
+  .filter((f) => f.endsWith(".md") && f !== "index.md")
+  .some((f) => {
+    const raw = fs.readFileSync(fileURLToPath(new URL(`../blog/${f}`, import.meta.url)), "utf8")
+    const frontmatter = raw.split("---")[1] ?? ""
+    if (/^draft:\s*true\s*$/m.test(frontmatter)) return false
+    const date = frontmatter.match(/^date:\s*(.+)$/m)?.[1]?.trim()
+    return !!date && +new Date(date) <= Date.now()
+  })
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig(withMermaid({
@@ -20,6 +40,9 @@ export default defineConfig(withMermaid({
     ["meta", { name: "twitter:title", content: "Plutonium - Build Production-Ready Rails Apps in Minutes" }],
     ["meta", { name: "twitter:description", content: "Build production-ready Rails applications in minutes, not days. Convention-driven, fully customizable. Built for the AI era." }],
     ["meta", { name: "twitter:image", content: "https://radioactive-labs.github.io/plutonium-core/og-image.png" }],
+    ...(hasPublishedPost
+      ? ([["link", { rel: "alternate", type: "application/rss+xml", title: "Plutonium Blog", href: `${hostname}/blog/feed.rss` }]] as HeadConfig[])
+      : []),
   ],
   ignoreDeadLinks: 'localhostLinks',
   srcExclude: ['superpowers/**'],
@@ -37,6 +60,7 @@ export default defineConfig(withMermaid({
           "getting-started/index.md",
           "guides/index.md",
           "reference/index.md",
+          "blog/index.md",
         ],
       }),
     ],
@@ -52,7 +76,9 @@ export default defineConfig(withMermaid({
       { text: "Getting Started", link: "/getting-started/" },
       { text: "Guides", link: "/guides/" },
       { text: "Reference", link: "/reference/" },
-      { text: "For AI Agents", link: "/ai" }
+      ...(hasPublishedPost ? [{ text: "Blog", link: "/blog/" }] : []),
+      { text: "For AI Agents", link: "/ai" },
+      { text: "Radioactive Labs", link: "https://radioactive-labs.github.io/" }
     ],
     sidebar: {
       '/getting-started/': [
@@ -122,6 +148,8 @@ export default defineConfig(withMermaid({
           text: "Quality",
           items: [
             { text: "Testing", link: "/guides/testing" },
+            { text: "Performance", link: "/guides/performance" },
+            { text: "Troubleshooting", link: "/guides/troubleshooting" },
           ]
         }
       ],
@@ -153,6 +181,7 @@ export default defineConfig(withMermaid({
             { text: "Definition", link: "/reference/resource/definition" },
             { text: "Query", link: "/reference/resource/query" },
             { text: "Actions", link: "/reference/resource/actions" },
+            { text: "Positioning & drag-to-reorder", link: "/reference/positioning" },
             { text: "CSV Export", link: "/reference/resource/export" },
           ]
         },
@@ -164,6 +193,7 @@ export default defineConfig(withMermaid({
             { text: "Controllers", link: "/reference/behavior/controllers" },
             { text: "Policies", link: "/reference/behavior/policies" },
             { text: "Interactions", link: "/reference/behavior/interactions" },
+            { text: "Async Interactions", link: "/reference/behavior/async-interactions" },
           ]
         },
         {
@@ -235,8 +265,56 @@ export default defineConfig(withMermaid({
     ],
     footer: {
       message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2024-present Stefan Froelich'
+      copyright: 'Copyright © 2024-present Stefan Froelich · <a href="https://radioactive-labs.github.io/" target="_blank" rel="noopener">Radioactive Labs</a>'
     }
   },
   cleanUrls: true,
+  async buildEnd(config: SiteConfig) {
+    const feed = new Feed({
+      title: "Plutonium",
+      description: "Release notes, design notes, and what's new in Plutonium.",
+      id: `${hostname}/blog/`,
+      link: `${hostname}/blog/`,
+      language: "en",
+      image: `${hostname}/og-image.png`,
+      favicon: `${hostname}/favicon.ico`,
+      copyright: "Copyright © 2024-present Stefan Froelich · Radioactive Labs",
+    })
+
+    const posts = await createContentLoader("blog/*.md", { render: true }).load()
+
+    posts
+      // Build-time cutoff: a feed cannot re-filter itself later, so a post dated
+      // ahead stays out until the next build after its date.
+      .filter(({ frontmatter }) => frontmatter.date && !frontmatter.draft)
+      .filter(({ frontmatter }) => +new Date(frontmatter.date) <= Date.now())
+      .sort((a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date))
+      .forEach(({ url, html, frontmatter }) => {
+        const link = `${hostname}${url}`
+        feed.addItem({
+          title: frontmatter.title,
+          id: link,
+          link,
+          description: frontmatter.description,
+          content: absolutize(html ?? "", link),
+          author: frontmatter.author ? [{ name: frontmatter.author }] : undefined,
+          category: frontmatter.tags?.map((name: string) => ({ name })),
+          date: new Date(frontmatter.date),
+        })
+      })
+
+    fs.mkdirSync(path.join(config.outDir, "blog"), { recursive: true })
+    fs.writeFileSync(path.join(config.outDir, "blog", "feed.rss"), feed.rss2())
+  },
 }))
+
+// A feed reader has no page to resolve links against, so everything the renderer
+// left relative has to be made absolute before it ships.
+function absolutize(html: string, link: string): string {
+  return html
+    // The renderer emits .html even though the site serves clean URLs.
+    .replace(new RegExp(`(="${base}[^"]*?)\\.html(?=["#])`, "g"), "$1")
+    .replaceAll(`="${base}`, `="${hostname}/`)
+    // Bare fragments would point at whatever page the reader happens to be showing.
+    .replaceAll('href="#', `href="${link}#`)
+}

data/docs/.vitepress/theme/blog.data.ts

@@ -0,0 +1,44 @@
+import { createContentLoader } from "vitepress"
+
+export interface Post {
+  title: string
+  url: string
+  description: string
+  author?: string
+  tags: string[]
+  date: { time: number; string: string }
+}
+
+declare const data: Post[]
+export { data }
+
+export default createContentLoader("blog/*.md", {
+  transform(raw): Post[] {
+    return raw
+      // The section index has no date: that's what separates it from a post.
+      .filter(({ frontmatter }) => frontmatter.date && !frontmatter.draft)
+      // Dated ahead means unpublished. The cutoff is applied at BUILD time, so a
+      // post goes live on the first build after its date, not on the date itself.
+      .filter(({ frontmatter }) => +new Date(frontmatter.date) <= Date.now())
+      .map(({ url, frontmatter }) => ({
+        title: frontmatter.title,
+        url,
+        description: frontmatter.description ?? "",
+        author: frontmatter.author,
+        tags: frontmatter.tags ?? [],
+        date: formatDate(frontmatter.date),
+      }))
+      .sort((a, b) => b.date.time - a.date.time)
+  },
+})
+
+function formatDate(raw: string | Date): Post["date"] {
+  const date = new Date(raw)
+  // Frontmatter dates parse as UTC midnight; nudge to midday so the rendered
+  // day doesn't slip backwards for readers behind UTC.
+  date.setUTCHours(12)
+  return {
+    time: +date,
+    string: date.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" }),
+  }
+}

data/docs/.vitepress/theme/components/BlogIndex.vue

@@ -0,0 +1,87 @@
+<template>
+  <section class="pu-section bi-section">
+    <div class="pu-section-inner">
+      <div class="pu-eyebrow">{{ eyebrow }}</div>
+      <h1 class="bi-h1">{{ title }}</h1>
+      <p class="bi-lede">{{ lede }}</p>
+
+      <a class="bi-rss" :href="withBase('/blog/feed.rss')">
+        <IconRss :size="15" :stroke-width="2" /> Subscribe via RSS
+      </a>
+
+      <div class="bi-list">
+        <a v-for="post in posts" :key="post.url" :href="withBase(post.url)" class="bi-post">
+          <time class="bi-date" :datetime="new Date(post.date.time).toISOString()">
+            {{ post.date.string }}
+          </time>
+          <span class="bi-body">
+            <span class="bi-title">{{ post.title }}</span>
+            <span v-if="post.description" class="bi-desc">{{ post.description }}</span>
+            <span v-if="post.tags.length" class="bi-tags">
+              <span v-for="tag in post.tags" :key="tag" class="bi-tag">{{ tag }}</span>
+            </span>
+          </span>
+          <IconArrowRight class="bi-arrow" :size="16" :stroke-width="2" />
+        </a>
+      </div>
+
+      <p v-if="!posts.length" class="bi-empty">No posts yet.</p>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { withBase } from "vitepress"
+import { IconArrowRight, IconRss } from "@tabler/icons-vue"
+import { data as posts } from "../blog.data"
+
+defineProps({
+  eyebrow: { type: String, default: "Blog" },
+  title: { type: String, required: true },
+  lede: { type: String, required: true },
+})
+</script>
+
+<style scoped>
+.bi-section { padding: 64px 24px 96px; }
+.bi-h1 { font-size: 36px; letter-spacing: -0.025em; margin: 0 0 12px; color: var(--pu-text); }
+.bi-lede { font-size: 16px; color: var(--pu-text-muted); max-width: 640px; margin: 0 0 20px; line-height: 1.55; }
+
+.bi-rss {
+  display: inline-flex; align-items: center; gap: 6px; margin-bottom: 40px;
+  font-size: 13px; font-weight: 500; color: var(--pu-text-muted); text-decoration: none;
+}
+.bi-rss:hover { color: var(--pu-accent); }
+
+.bi-list { border-left: 2px solid var(--pu-accent); padding-left: 24px; max-width: 760px; }
+.bi-post {
+  display: flex; gap: 20px; align-items: flex-start;
+  padding: 18px 0; border-bottom: 1px solid var(--pu-border-soft);
+  color: var(--pu-text); text-decoration: none;
+}
+.bi-post:last-child { border-bottom: none; }
+.bi-post:hover .bi-title { color: var(--pu-accent); }
+.bi-post:hover .bi-arrow { transform: translateX(2px); color: var(--pu-accent); }
+
+.bi-date {
+  flex-shrink: 0; width: 124px; padding-top: 2px;
+  font-size: 12.5px; color: var(--pu-text-faint); font-variant-numeric: tabular-nums;
+}
+.bi-body { display: flex; flex-direction: column; gap: 4px; flex: 1; }
+.bi-title { font-weight: 600; font-size: 16px; letter-spacing: -0.01em; }
+.bi-desc { font-size: 13.5px; color: var(--pu-text-muted); line-height: 1.5; }
+.bi-tags { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 4px; }
+.bi-tag {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; font-weight: 600;
+  color: var(--pu-text-faint); border: 1px solid var(--pu-border-soft);
+  border-radius: 3px; padding: 1px 6px;
+}
+.bi-arrow { color: var(--pu-text-faint); transition: transform 0.15s ease, color 0.15s ease; flex-shrink: 0; margin-top: 4px; }
+.bi-empty { color: var(--pu-text-muted); font-size: 14px; }
+
+@media (max-width: 640px) {
+  .bi-post { flex-direction: column; gap: 6px; }
+  .bi-date { width: auto; padding-top: 0; }
+  .bi-arrow { display: none; }
+}
+</style>

data/docs/.vitepress/theme/components/BlogMeta.vue

@@ -0,0 +1,47 @@
+<template>
+  <div class="bm">
+    <div class="bm-line">
+      <time v-if="dateString" :datetime="isoDate">{{ dateString }}</time>
+      <span v-if="frontmatter.author" class="bm-sep">·</span>
+      <span v-if="frontmatter.author">{{ frontmatter.author }}</span>
+    </div>
+    <a class="bm-back" :href="withBase('/blog/')">
+      <IconArrowLeft :size="14" :stroke-width="2" /> All posts
+    </a>
+  </div>
+</template>
+
+<script setup>
+import { computed } from "vue"
+import { useData, withBase } from "vitepress"
+import { IconArrowLeft } from "@tabler/icons-vue"
+
+const { frontmatter } = useData()
+
+// Frontmatter dates arrive as a Date (YAML-parsed) or a string, depending on quoting.
+const parsed = computed(() => (frontmatter.value.date ? new Date(frontmatter.value.date) : null))
+const isoDate = computed(() => parsed.value?.toISOString())
+const dateString = computed(() =>
+  parsed.value?.toLocaleDateString("en-US", {
+    year: "numeric", month: "long", day: "numeric", timeZone: "UTC",
+  })
+)
+</script>
+
+<style scoped>
+.bm {
+  margin: 0 0 40px;
+  padding-bottom: 20px;
+  border-bottom: 1px solid var(--pu-border-soft);
+}
+.bm-line {
+  font-size: 14px; color: var(--pu-text-muted);
+  display: flex; align-items: center; gap: 7px;
+}
+.bm-sep { color: var(--pu-text-faint); }
+.bm-back {
+  display: inline-flex; align-items: center; gap: 5px; margin-top: 14px;
+  font-size: 13px; font-weight: 500; color: var(--pu-accent); text-decoration: none;
+}
+.bm-back:hover { text-decoration: underline; }
+</style>