rsc-universal 0.1.1

package/skills/phoenix/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: phoenix
+
+should_trigger:
+  - prompt: "Build a LiveView CRUD page for products with a list, create form and delete."
+    why: Core LiveView use — mount/handle_event, streams, forms, verified routes.
+  - prompt: "How should I structure the Accounts context so my controllers stay thin?"
+    why: Context boundary — the central Phoenix mental model (web is a thin caller).
+  - prompt: "Set up passwordless / magic-link login with phx.gen.auth."
+    why: Phoenix 1.8 magic-link auth default plus the scope wiring it scaffolds.
+  - prompt: "My LiveView re-renders the entire message list every time one row is added — how do I fix it?"
+    why: Non-obvious symptom whose real fix is streams (off-socket collections); names no Phoenix API directly.
+  - prompt: "Every post in my loop fires a separate query for its author — how do I stop the N+1?"
+    why: Web-app data layer; Ecto preload. The symptom, not the API name, is the trigger.
+  - prompt: "Crea un context Comandes i un LiveView per gestionar-les amb accés per usuari."
+    why: Catalan trigger — context + LiveView + scope-based per-user access.
+
+should_not_trigger:
+  - prompt: "Design a supervision tree and restart strategy for a pool of workers."
+    route_to: elixir
+    why: Pure OTP/runtime — no web, Ecto or LiveView layer.
+  - prompt: "Add a GIN index and tune this slow Postgres query plan."
+    route_to: postgresdb
+    why: Raw SQL/index design below the Ecto line, framework-independent.
+  - prompt: "Containerize the release and deploy it to Fly.io."
+    route_to: fly-io
+    why: Shipping/runtime of the release, not Phoenix application code.
+  - prompt: "Build the REST API in Django with DRF serializers."
+    route_to: django
+    why: A different web framework, explicitly named — not Phoenix.
+
+capability:
+  - scenario: "Implement a Catalog context managing a Product schema plus a LiveView index, scoped to the current user's org, with a create form and tests."
+    must_include:
+      - "Context functions are the public API; the LiveView/controller never calls Repo or builds a query directly"
+      - "Ecto.Changeset casts and validates (required fields, price > 0) at the boundary"
+      - "The scope (current user/org) is threaded into every context function and applied inside the query (where org_id ==), not in a post-fetch if"
+      - "LiveView uses stream/stream_insert for the product list, not a full-list assign"
+      - "Form uses to_form/2 and renders changeset errors on {:error, changeset}"
+      - "Verified routes (~p sigil) used for links/redirects, not hardcoded path strings"
+      - "Phoenix.LiveViewTest with live/2 and render_submit/render_click; context logic tested with DataCase"

package/skills/phoenix/references/auth-and-scopes.md

@@ -0,0 +1,82 @@
+# Auth & scopes — depth
+
+Phoenix 1.8 makes authorization a property of data access via **scopes**, and `mix phx.gen.auth` scaffolds the whole login flow around them.
+
+## `mix phx.gen.auth` in 1.8
+
+```bash
+mix phx.gen.auth Accounts User users
+```
+
+Defaults to **magic-link (passwordless) auth**: the user enters an email, receives a one-time login link, and is signed in — no password to store or leak. Email+password is still available if you opt in. The generator produces:
+
+- The `Accounts` context (`User`, tokens, registration/login functions).
+- LiveViews for login, registration, settings, confirmation.
+- A `require_authenticated_user` plug/on_mount hook.
+- A **sudo mode** re-auth gate (`require_sudo_mode`-style) for sensitive operations (changing email/password) — recent confirmation is required even when already logged in.
+- The **default scope** wired into the router and `conn.assigns` / `socket.assigns`.
+
+## Scopes — secure-by-default access
+
+A scope is a struct carrying the current actor and whatever it is scoped to (user, org/tenant). Generators thread it through every context function and into every query.
+
+```elixir
+defmodule MyApp.Accounts.Scope do
+  defstruct [:user, :org]
+  def for_user(%User{} = user), do: %__MODULE__{user: user, org: user.org}
+end
+```
+
+```elixir
+# Router puts the scope on assigns once.
+# Every context function takes it and filters by it.
+def list_products(%Scope{} = scope) do
+  from(p in Product, where: p.org_id == ^scope.org.id) |> Repo.all()
+end
+
+def get_product!(%Scope{} = scope, id) do
+  from(p in Product, where: p.id == ^id and p.org_id == ^scope.org.id) |> Repo.one!()
+end
+```
+
+Rule: the scope filter goes **in the query**, not in an `if` after the fetch. Why: `get_product!(scope, other_orgs_id)` then raises `NoResultsError` (a clean 404) instead of returning a row you forgot to check. The unsafe path stops compiling/working, the safe path is the only path.
+
+## In LiveView
+
+```elixir
+# router.ex
+live_session :authenticated, on_mount: [{MyAppWeb.UserAuth, :require_authenticated}] do
+  live "/products", ProductLive.Index, :index
+end
+
+# the on_mount hook puts current_scope on the socket; use it everywhere:
+def mount(_p, _s, socket) do
+  {:ok, stream(socket, :products, Catalog.list_products(socket.assigns.current_scope))}
+end
+```
+
+## Sudo mode for sensitive actions
+
+```elixir
+# Re-confirm recent authentication before allowing email/password changes.
+plug :require_sudo_mode when action in [:update_email, :update_password]
+```
+
+If the user authenticated too long ago, they are bounced to re-confirm. This limits the blast radius of a hijacked session.
+
+## Testing authz
+
+```elixir
+# DataCase — the scope filter is the authorization; test that cross-scope access fails.
+test "get_product!/2 cannot read another org's product", %{scope: scope} do
+  other = product_fixture(scope_fixture())          # different org
+  assert_raise Ecto.NoResultsError, fn -> Catalog.get_product!(scope, other.id) end
+end
+
+# ConnCase / LiveViewTest — unauthenticated request redirects to login.
+test "redirects when not logged in", %{conn: conn} do
+  assert {:error, {:redirect, %{to: "/users/log-in"}}} = live(conn, ~p"/products")
+end
+```
+
+Rule: test authorization at the context with `DataCase` (the scope filter is where authz lives), and test the redirect/gate at the web layer with `ConnCase`/`LiveViewTest`. Why: proving the query refuses cross-scope rows is the real security assertion; the web test just proves the gate is wired.

package/skills/phoenix/references/ecto-patterns.md

@@ -0,0 +1,93 @@
+# Ecto patterns — depth
+
+Ecto is the data layer: `Repo` (the gateway to the DB), schemas (struct + field map), `Ecto.Changeset` (cast + validate + constraints), `Ecto.Multi` (transactional pipelines), `Ecto.Query`. `phoenix_ecto` adds the Phoenix integration and the concurrent SQL sandbox for tests.
+
+## Changeset recipes
+
+A changeset casts external params, applies validations, and maps DB constraints to field errors.
+
+```elixir
+def changeset(product, attrs) do
+  product
+  |> cast(attrs, [:name, :price, :sku, :org_id])
+  |> validate_required([:name, :price, :org_id])
+  |> validate_number(:price, greater_than: 0)
+  |> validate_length(:name, max: 120)
+  |> unique_constraint(:sku)                 # turns a DB unique violation into a field error
+  |> foreign_key_constraint(:org_id)
+end
+```
+
+Rule: validate in the changeset, not with `try/rescue`. `unique_constraint`/`foreign_key_constraint` require the matching DB index/constraint — they convert the DB error into `{:error, changeset}` instead of an exception. Why: only the database can atomically enforce uniqueness under concurrency; the changeset just translates the failure.
+
+Use a separate changeset per operation when rules differ (`registration_changeset` vs `update_changeset`) rather than one changeset with conditional branches.
+
+## `Ecto.Multi` — atomic multi-write
+
+```elixir
+def place_order(scope, cart) do
+  Ecto.Multi.new()
+  |> Ecto.Multi.insert(:order, Order.changeset(%Order{org_id: scope.org.id}, cart))
+  |> Ecto.Multi.insert_all(:items, OrderItem, &build_items(&1.order, cart))
+  |> Ecto.Multi.update(:inventory, fn _ -> decrement_stock(cart) end)
+  |> Repo.transaction()
+end
+# => {:ok, %{order: order, items: ..., inventory: ...}}  or  {:error, step, changeset, changes_so_far}
+```
+
+Every step commits or the whole thing rolls back. Each step can read the results of prior steps via the function form. Pattern-match `{:error, failed_step, changeset, _}` to know which step failed.
+
+## Queries & preloads — killing N+1
+
+```elixir
+import Ecto.Query
+
+# Preload (two queries: posts, then all authors) — preferred for has_many.
+Post |> preload(:author) |> Repo.all()
+
+# Join + preload in one query — for filtering/ordering by the association.
+from(p in Post, join: a in assoc(p, :author), where: a.active, preload: [author: a])
+|> Repo.all()
+
+# Scoped, paginated, ordered.
+from(p in Product,
+  where: p.org_id == ^scope.org.id,
+  order_by: [desc: p.inserted_at],
+  limit: ^limit, offset: ^offset
+) |> Repo.all()
+```
+
+Rule: never touch `record.assoc` inside a loop without preloading first — that is the N+1. Use `preload` for plain loading; use `join: ... preload:` when you also filter or sort by the association.
+
+## Migrations & constraints
+
+```elixir
+def change do
+  create table(:products) do
+    add :name, :string, null: false
+    add :sku, :string, null: false
+    add :org_id, references(:orgs, on_delete: :delete_all), null: false
+    timestamps()
+  end
+  create unique_index(:products, [:sku])
+  create index(:products, [:org_id])         # back the scope filter with an index
+end
+```
+
+Migrations are forward-only history: write a new migration to change schema, never edit a migration that has shipped. Constraints (`null: false`, `unique_index`, FK) belong in the migration; the changeset translates their violations into field errors. Index the columns the scope filters on, or every scoped query is a table scan.
+
+## SQL sandbox for tests
+
+```elixir
+# config/test.exs
+config :my_app, MyApp.Repo, pool: Ecto.Adapters.SQL.Sandbox
+
+# test/support/data_case.ex setup
+setup tags do
+  pid = Ecto.Adapters.SQL.Sandbox.start_owner!(MyApp.Repo, shared: not tags[:async])
+  on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
+  :ok
+end
+```
+
+Each test runs in its own transaction that is rolled back at the end, so tests stay isolated and can run `async: true` concurrently. LiveView/Conn tests that spawn processes need `shared: true` (non-async) so the spawned process sees the same sandbox connection.

package/skills/phoenix/references/liveview.md

@@ -0,0 +1,134 @@
+# LiveView (1.1) — depth
+
+Targets LiveView 1.1.x on Phoenix 1.8.7. LiveView holds UI state in `socket.assigns`, renders HEEx, and reacts to events over a persistent WebSocket (with a dead HTTP render first).
+
+## Lifecycle in detail
+
+```elixir
+def mount(params, session, socket) do
+  # Runs twice: once for the dead (HTTP) render, once on WS connect.
+  # Gate expensive/subscription work on connected?/1.
+  if connected?(socket), do: Phoenix.PubSub.subscribe(MyApp.PubSub, "products")
+  {:ok, stream(socket, :products, Catalog.list_products(socket.assigns.current_scope))}
+end
+
+def handle_params(params, _uri, socket) do
+  # Every live_patch / URL change lands here. Use for tab/filter/pagination state.
+  {:noreply, apply_action(socket, socket.assigns.live_action, params)}
+end
+
+def handle_event("delete", %{"id" => id}, socket) do
+  product = Catalog.get_product!(socket.assigns.current_scope, id)
+  {:ok, _} = Catalog.delete_product(socket.assigns.current_scope, product)
+  {:noreply, stream_delete(socket, :products, product)}
+end
+
+def handle_info({:created, product}, socket) do
+  # External event (PubSub broadcast, send/2 from a Task). Apply to the stream.
+  {:noreply, stream_insert(socket, :products, product, at: 0)}
+end
+```
+
+`assign/2,3` for scalar state; `assign_new/3` to avoid recomputing on reconnect. Keep assigns small — they are state held per connected socket.
+
+## Streams — collections without server-held lists
+
+A stream keeps the collection in the DOM, not in `socket.assigns`. The server tracks only DOM ids, so a single `stream_insert/3` ships one row.
+
+```elixir
+stream(socket, :products, products)            # initial load
+stream_insert(socket, :products, p, at: 0)     # prepend; at: -1 appends
+stream_delete(socket, :products, p)            # remove one row
+stream(socket, :products, [], reset: true)     # clear and reload
+```
+
+```heex
+<table>
+  <tbody id="products" phx-update="stream">
+    <tr :for={{dom_id, p} <- @streams.products} id={dom_id}>
+      <td>{p.name}</td>
+      <td>{p.price}</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+The container needs an `id` and `phx-update="stream"`; each row's `id` must come from the stream's `{dom_id, item}`. For per-row change tracking (a row that re-renders independently), wrap the row in a `Phoenix.LiveComponent` keyed by id — only that component re-diffs.
+
+## Forms with `to_form/2`
+
+```elixir
+def mount(_p, _s, socket) do
+  {:ok, assign(socket, :form, to_form(Catalog.change_product(%Product{})))}
+end
+
+def handle_event("validate", %{"product" => attrs}, socket) do
+  form = %Product{} |> Catalog.change_product(attrs) |> Map.put(:action, :validate) |> to_form()
+  {:noreply, assign(socket, :form, form)}
+end
+
+def handle_event("save", %{"product" => attrs}, socket) do
+  case Catalog.create_product(socket.assigns.current_scope, attrs) do
+    {:ok, _product} -> {:noreply, socket |> put_flash(:info, "Created") |> push_navigate(to: ~p"/products")}
+    {:error, changeset} -> {:noreply, assign(socket, :form, to_form(changeset))}
+  end
+end
+```
+
+```heex
+<.form for={@form} phx-change="validate" phx-submit="save">
+  <.input field={@form[:name]} label="Name" />
+  <.button>Save</.button>
+</.form>
+```
+
+`to_form/2` wraps a changeset; rendering the same form back on `{:error, changeset}` surfaces field errors automatically. Setting `:action` makes "validate" errors show without a submit.
+
+## Uploads
+
+```elixir
+socket = allow_upload(socket, :photo, accept: ~w(.jpg .png), max_entries: 1)
+# in save: consume_uploaded_entries(socket, :photo, fn %{path: path}, _entry -> ... end)
+```
+
+## JS commands — client interactivity without a round trip
+
+```heex
+<button phx-click={JS.toggle(to: "#menu") |> JS.add_class("open", to: "#menu")}>Menu</button>
+```
+
+`Phoenix.LiveView.JS` runs show/hide/toggle/transition/dispatch on the client with no server message — use it for purely visual state.
+
+## Colocated hooks & ColocatedJS (1.1, requires Phoenix 1.8+)
+
+Define a JS hook next to the element that uses it; the compiler extracts it into the bundle.
+
+```heex
+<div id="chart" phx-hook=".Chart" data-series={Jason.encode!(@series)}>
+  <script :type={Phoenix.LiveView.ColocatedHook} name=".Chart">
+    export default { mounted() { renderChart(this.el); } }
+  </script>
+</div>
+```
+
+`ColocatedJS` extracts arbitrary colocated `<script>` modules. LiveView 1.1 also ships official TypeScript types for the JS client and **keyed comprehensions** (`:for` tracks items by key for finer diffs).
+
+## Async assigns
+
+Offload slow loads so mount returns immediately.
+
+```elixir
+def mount(_p, _s, socket) do
+  {:ok, assign_async(socket, :stats, fn -> {:ok, %{stats: Reports.expensive_stats()}} end)}
+end
+```
+
+```heex
+<.async_result :let={stats} assign={@stats}>
+  <:loading>Computing…</:loading>
+  <:failed :let={_reason}>Could not load.</:failed>
+  {stats.total}
+</.async_result>
+```
+
+`assign_async/3` runs the work in a Task and pushes the result; the template renders loading/failed/ready states. Use it instead of blocking `mount/3` on a slow query.

package/skills/phoenix/scripts/verify.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# verify.sh — read-only gates for a Phoenix / Elixir target.
+#
+# When run inside a mix project it runs the standard project gates:
+#   - mix format --check-formatted        (style)
+#   - mix compile --warnings-as-errors    (warning-free compile)
+#   - mix test                            (only if a test/ dir exists)
+#
+# It never fails a toolchain-free or empty target: it exits 0 with a skip note
+# when mix is absent or there is no mix.exs to check. Read-only: no writes, no
+# network and no database are required to pass the compile/format gates.
+#
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory — nothing to check. SKIP."
+  exit 0
+fi
+
+# Toolchain gate: no mix on PATH -> skip cleanly (never fail without a toolchain).
+if ! command -v mix >/dev/null 2>&1; then
+  echo "verify: 'mix' not found on PATH — Elixir/Phoenix toolchain not installed. SKIP."
+  exit 0
+fi
+
+# Find a mix project root (a directory containing mix.exs), shallowest first.
+mix_root=""
+if [ -f "$TARGET/mix.exs" ]; then
+  mix_root="$TARGET"
+else
+  mix_root="$(find "$TARGET" -maxdepth 4 -name mix.exs -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null \
+    | awk '{ print gsub(/\//,"/"), $0 }' | sort -n | head -n1 | cut -d' ' -f2- || true)"
+  [ -n "$mix_root" ] && mix_root="$(dirname "$mix_root")"
+fi
+
+if [ -z "$mix_root" ]; then
+  echo "verify: no mix.exs under '$TARGET' — not a mix project, nothing to check. SKIP."
+  exit 0
+fi
+
+echo "verify: mix project root -> $mix_root"
+status=0
+
+echo "verify: mix format --check-formatted"
+if ! ( cd "$mix_root" && mix format --check-formatted ); then
+  echo "verify: FAIL — files are not formatted (run: mix format)"
+  status=1
+fi
+
+echo "verify: mix compile --warnings-as-errors"
+if ! ( cd "$mix_root" && mix compile --warnings-as-errors ); then
+  echo "verify: FAIL — compile produced warnings or errors"
+  status=1
+fi
+
+if [ -d "$mix_root/test" ]; then
+  echo "verify: mix test"
+  if ! ( cd "$mix_root" && mix test ); then
+    echo "verify: FAIL — test suite did not pass"
+    status=1
+  fi
+else
+  echo "verify: no test/ directory — skipping mix test."
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "verify: OK"
+fi
+exit "$status"