Files
chess-endgame-trainer/AGENTS.md
T
owenrees 7cb7298236 Add user accounts, roles, and admin gating
- Scaffold password auth (email or username) with phx.gen.auth; no magic links
- Add role (member/moderator/admin/super_admin) and plan (free/premium) enums
- Gate /admin behind admin-or-above via plug + on_mount; hide the nav link
- Add mix accounts.promote for CLI role changes
- Disable email confirmation by confirming accounts at registration

Closes #3
2026-11-03 15:48:50 +01:00

6.7 KiB
Raw Blame History

Phoenix 1.8 web app — an endgame trainer. LiveView 1.2, Ecto/Postgres, chessground for board rendering. Modules are Chesstrainer and ChesstrainerWeb.

Graft — repo context graph

This repo is indexed in graft/: small linked markdown nodes that explain each system and carry exact file:line spans, kept in sync with the code through git.

For ANY task here — understanding how something works, finding where code lives, or scoping a change — get context from the graph before grepping or opening source files. Re-ask freely (it's cheap) and reuse literal identifiers you already have (symbol, error string, file name) as the query. New to this repo? Run graft map first — a token-budgeted orientation (dir clusters, hubs, hotspots), no LLM, no key.

  • Run graft ask "<your question>" --source → ranked nodes with the relevant code spans inlined (each hit's ≤8-line crux by default; --full for whole definitions when the crux isn't enough). Match the tool to the task shape: for understanding or editing, the top node IS the answer — cite its covers: file:line spans and edit straight from --source. For exhaustive tasks ("every occurrence / every caller of this pattern"), ranked results are top-N, not complete — run graft grep "<literal>" instead (exhaustive over indexed files, grouped by enclosing symbol), falling back to raw grep -rn only for unindexed files.
  • graft skeleton <file> → every definition's signature + span, ~10× cheaper than reading the file; use it to skim an API surface.
  • graft callers <symbol> gives precomputed, exact edges — who calls this. Add --direction out for what it calls, or --depth N to walk transitively for the full blast radius. For structural questions, skip ranking and use this directly.
  • Or browse: graft/INDEX.md lists every node; follow the links.
  • Monorepos and folders of multiple repos rank fairly across sub-projects — hits carry [scope/] labels naming which one they're from. Narrow with graft ask "<task>" --in <scope>/ once you know where you're working.

If a returned span is truncated ("+N more lines"), open the file at that exact range before finalizing. Only open source files when a node genuinely lacks a needed detail, and then at the exact file:line the node points to — never re-read whole files.

After big code changes, refresh the graph with graft build (deterministic, no API key, $0).

Coding standards

Read CODING_STANDARDS.md before writing code. Read the section for the layer you're touching: Elixir, Ecto, Phoenix, HEEx, LiveView, Forms, Assets, or Testing.

Done

Run mix precommit and fix what it flags.

Type-check risky changes with mix dialyzer (not part of mix precommit; the first run builds a PLT and is slow).

Agent skills

Issue tracker

Issues live in GitHub Issues for TheRealOwenRees/chess-endgame-trainer, driven by the gh CLI. See docs/agents/issue-tracker.md.

Triage labels

The five canonical triage roles, each label string equal to its name (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.

Domain docs

Single-context: GLOSSARY.md and docs/adr/ at the repo root. See docs/agents/domain.md.

Authentication

  • Always handle authentication flow at the router level with proper redirects
  • Always be mindful of where to place routes. phx.gen.auth creates multiple router plugs and live_session scopes:
    • A plug :fetch_current_scope_for_user that is included in the default browser pipeline
    • A plug :require_authenticated_user that redirects to the log in page when the user is not authenticated
    • A live_session :current_user scope - for routes that need the current user but don't require authentication, similar to :fetch_current_scope_for_user
    • A live_session :require_authenticated_user scope - for routes that require authentication, similar to the plug with the same name
    • In both cases, a @current_scope is assigned to the Plug connection and LiveView socket
    • A plug redirect_if_user_is_authenticated that redirects to a default path in case the user is authenticated - useful for a registration page that should only be shown to unauthenticated users
  • Always let the user know in which router scopes, live_session, and pipeline you are placing the route, AND SAY WHY
  • phx.gen.auth assigns the current_scope assign - it does not assign a current_user assign
  • Always pass the assign current_scope to context modules as first argument. When performing queries, use current_scope.user to filter the query results
  • To derive/access current_user in templates, always use the @current_scope.user, never use @current_user in templates or LiveViews
  • Never duplicate live_session names. A live_session :current_user can only be defined once in the router, so all routes for the live_session :current_user must be grouped in a single block
  • Anytime you hit current_scope errors or the logged in session isn't displaying the right content, always double check the router and ensure you are using the correct plug and live_session as described below

Routes that require authentication

LiveViews that require login should always be placed inside the existing live_session :require_authenticated_user block:

scope "/", AppWeb do
  pipe_through [:browser, :require_authenticated_user]

  live_session :require_authenticated_user,
    on_mount: [{ChesstrainerWeb.UserAuth, :require_authenticated}] do
    # phx.gen.auth generated routes
    live "/users/settings", UserLive.Settings, :edit
    live "/users/settings/confirm-email/:token", UserLive.Settings, :confirm_email
    # our own routes that require logged in user
    live "/", MyLiveThatRequiresAuth, :index
  end
end

Controller routes must be placed in a scope that sets the :require_authenticated_user plug:

scope "/", AppWeb do
  pipe_through [:browser, :require_authenticated_user]

  get "/", MyControllerThatRequiresAuth, :index
end

Routes that work with or without authentication

LiveViews that can work with or without authentication, always use the existing :current_user scope, ie:

scope "/", MyAppWeb do
  pipe_through [:browser]

  live_session :current_user,
    on_mount: [{ChesstrainerWeb.UserAuth, :mount_current_scope}] do
    # our own routes that work with or without authentication
    live "/", PublicLive
  end
end

Controllers automatically have the current_scope available if they use the :browser pipeline.