mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 03:32:06 +00:00
- 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
130 lines
6.7 KiB
Markdown
130 lines
6.7 KiB
Markdown
Phoenix 1.8 web app — an endgame trainer. LiveView 1.2, Ecto/Postgres, chessground for board rendering. Modules are `Chesstrainer` and `ChesstrainerWeb`.
|
||
|
||
<!-- graft:start -->
|
||
## 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).
|
||
<!-- graft:end -->
|
||
|
||
## 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`.
|
||
|
||
|
||
<!-- phoenix-gen-auth-start -->
|
||
## 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.
|
||
|
||
<!-- phoenix-gen-auth-end --> |