add blog page for each feature. Update api conventions

precommit

Author: Ughuuu

apps/game_server_core/lib/game_server/api_conventions.ex

@@ -21,8 +21,21 @@ defmodule GameServer.ApiConventions do
           message: String.t()
         }
 
-  @core "apps/game_server_core/lib"
-  @web "apps/game_server_web/lib"
+  # The same checks run in every host repo (polyglot, the starter), where
+  # core/web live under deps and the host's own code under lib/ and
+  # modules/*/lib - so the scan roots are discovered, not hardcoded. Only
+  # directories that exist take part.
+  @schema_roots ["apps/game_server_core/lib", "lib", "modules"]
+  @source_roots ["apps/game_server_web/lib", "lib", "modules"]
+
+  defp schema_dirs, do: existing([dep_dir("game_server_core") | @schema_roots])
+  defp source_dirs, do: existing([dep_dir("game_server_web") | @source_roots])
+
+  # In a host repo core/web are deps; their code obeys the rules too, and a
+  # violation there means the host pulled a bad version - worth failing on.
+  defp dep_dir(app), do: Path.join(["deps", app, "apps", app, "lib"])
+
+  defp existing(paths), do: paths |> Enum.filter(&File.dir?/1) |> Enum.uniq()
 
   # Durations must name their unit. `_at` is for instants, not durations.
   @duration_units ~w(ms sec seconds min minutes hours days)
@@ -39,7 +52,8 @@ defmodule GameServer.ApiConventions do
        hyphenated_route_paths() ++
        nullable_string_schemas() ++
        hand_rolled_meta() ++
-       hand_rolled_page_params())
+       hand_rolled_page_params() ++
+       stale_documented_routes())
     |> Enum.sort_by(&{&1.rule, &1.file, &1.line})
   end
 
@@ -51,7 +65,10 @@ defmodule GameServer.ApiConventions do
   defp nullable_strings_not_coalesced do
     nullable = nullable_schema_fields()
 
-    for {file, line, text} <- source_lines(@web),
+    for {file, line, text} <- source_lines(source_dirs()),
+        # Only code that writes JSON responses: a `key: var.field` line in a
+        # context is usually changeset attrs, where nil is fine.
+        String.contains?(file, "_web/"),
         not live_view?(file),
         [_, key, _var, field] <- [Regex.run(~r/^\s*(\w+): ([a-z_]+)\.(\w+),?\s*$/, text)],
         Map.has_key?(nullable, field),
@@ -71,7 +88,7 @@ defmodule GameServer.ApiConventions do
   # every serializer. Such schemas encode through `GameServer.SchemaJSON`.
 
   defp derived_encoders_with_nullable_strings do
-    for {file, line, text} <- source_lines(@core),
+    for {file, line, text} <- source_lines(schema_dirs()),
         String.contains?(text, "@derive {Jason.Encoder"),
         schema_has_nullable_string?(file) do
       %{
@@ -86,7 +103,7 @@ defmodule GameServer.ApiConventions do
   # ── R3: instants are `*_at`, and nothing else is ───────────────────────────
 
   defp instants_not_suffixed do
-    for {file, line, text} <- source_lines(@core),
+    for {file, line, text} <- source_lines(schema_dirs()),
         [_, field] <- [Regex.run(~r/^\s*field :(\w+), :utc_datetime/, text)],
         not String.ends_with?(field, "_at") do
       %{
@@ -101,7 +118,7 @@ defmodule GameServer.ApiConventions do
   # ── R4: durations name their unit ──────────────────────────────────────────
 
   defp durations_without_unit do
-    for {file, line, text} <- source_lines(@core) ++ source_lines(@web),
+    for {file, line, text} <- source_lines(schema_dirs() ++ source_dirs()),
         [_, name] <- [Regex.run(~r/^\s*setting\(?:(\w+), :integer/, text)],
         duration_name?(name),
         not unit_suffixed?(name) do
@@ -124,7 +141,7 @@ defmodule GameServer.ApiConventions do
   # ── R5: route paths use underscores ────────────────────────────────────────
 
   defp hyphenated_route_paths do
-    for {file, line, text} <- source_lines(@web),
+    for {file, line, text} <- source_lines(source_dirs()),
         String.contains?(file, "router"),
         [_, verb, path] <-
           [Regex.run(~r/^\s*(get|post|put|patch|delete|live) "(\/[^"]*)"/, text)],
@@ -145,7 +162,7 @@ defmodule GameServer.ApiConventions do
   # semantic there (`ends_at: null` = permanent).
 
   defp nullable_string_schemas do
-    for {file, line, text} <- source_lines(@web),
+    for {file, line, text} <- source_lines(source_dirs()),
         String.contains?(text, "nullable: true"),
         String.contains?(text, "type: :string"),
         not String.contains?(text, "format:"),
@@ -166,7 +183,7 @@ defmodule GameServer.ApiConventions do
   # emitting three, four and six keys.
 
   defp hand_rolled_meta do
-    for {file, line, text} <- source_lines(@web),
+    for {file, line, text} <- source_lines(source_dirs()),
         controller?(file),
         Regex.match?(~r/^\s*(total_pages|has_more):/, text),
         not String.contains?(text, "%Schema{") do
@@ -185,7 +202,7 @@ defmodule GameServer.ApiConventions do
   # `min(size, 100)`, which ignored the configurable `max_page_size` limit.
 
   defp hand_rolled_page_params do
-    for {file, line, text} <- source_lines(@web),
+    for {file, line, text} <- source_lines(source_dirs()),
         controller?(file),
         String.contains?(text, ~s(params["page_size"])) or
           String.contains?(text, ~s(params["page"])) do
@@ -200,6 +217,91 @@ defmodule GameServer.ApiConventions do
 
   defp controller?(file), do: String.contains?(file, "/controllers/")
 
+  # ── R9: docs reference only routes that exist ──────────────────────────────
+  #
+  # Guides and specs name concrete `/api/v1/...` paths; a rename that misses
+  # one leaves documentation teaching a 404. Prefixes of real routes are fine
+  # ("endpoints live under /api/v1/chat"), as are file paths.
+
+  @doc_dirs ["priv/docs", "docs"]
+
+  defp stale_documented_routes do
+    case declared_route_paths() do
+      [] -> []
+      declared -> stale_documented_routes(declared)
+    end
+  end
+
+  defp stale_documented_routes(declared) do
+    for dir <- @doc_dirs,
+        file <- Path.wildcard(Path.join(dir, "**/*.md")),
+        {text, line} <- file |> File.read!() |> String.split("\n") |> Enum.with_index(1),
+        path <- documented_api_paths(text),
+        not known_or_prefix?(path, declared) do
+      %{
+        rule: "R9-doc-route",
+        file: file,
+        line: line,
+        message: "documents `#{path}`, which matches no declared route"
+      }
+    end
+  end
+
+  defp documented_api_paths(line) do
+    ~r|/api/v1/[A-Za-z0-9_\-/:{}]*[A-Za-z0-9_}]|
+    |> Regex.scan(line)
+    |> List.flatten()
+    |> Enum.reject(&(String.contains?(&1, "controller") or String.ends_with?(&1, ".ex")))
+    |> Enum.map(&normalize_path/1)
+  end
+
+  defp normalize_path(path) do
+    Regex.replace(~r/(:\w+|\{\w+\})/, path, "{}")
+  end
+
+  # A documented path is fine when a declared route matches it — params on
+  # either side are wildcards, so `/payments/validate/google` satisfies
+  # `/payments/validate/{}` — or when it is a prefix of one ("endpoints live
+  # under /api/v1/chat").
+  defp known_or_prefix?(path, declared) do
+    Enum.any?(declared, fn route ->
+      Regex.match?(wildcard_regex(route, ""), path) or
+        Regex.match?(wildcard_regex(path, "(/|$)"), route)
+    end)
+  end
+
+  defp wildcard_regex(pattern, tail) do
+    inner =
+      pattern
+      |> Regex.escape()
+      |> String.replace("\\{\\}", "[^/]+")
+
+    Regex.compile!("^" <> inner <> if(tail == "", do: "$", else: tail))
+  end
+
+  @doc """
+  Every path the compiled router serves, `:params` as `{}`.
+
+  Read from `Phoenix.Router.routes/1` rather than parsed from source — routes
+  live inside `scope` blocks, so the literal strings in the source are
+  suffixes, not full paths.
+  """
+  @spec declared_route_paths() :: [String.t()]
+  def declared_route_paths do
+    [GameServerHost.Router, GameServerWeb.Router]
+    |> Enum.find(&Code.ensure_loaded?/1)
+    |> case do
+      nil ->
+        []
+
+      router ->
+        router
+        |> Phoenix.Router.routes()
+        |> Enum.map(&normalize_path(&1.path))
+        |> Enum.uniq()
+    end
+  end
+
   # ── Shared analysis ────────────────────────────────────────────────────────
 
   @doc """
@@ -209,7 +311,7 @@ defmodule GameServer.ApiConventions do
   @spec nullable_schema_fields() :: %{String.t() => String.t()}
   def nullable_schema_fields do
     per_schema =
-      for path <- ex_files(@core),
+      for path <- ex_files(schema_dirs()),
           [_, table, body] <- [Regex.run(~r/schema "(\w+)" do(.*?)\n  end/s, File.read!(path))] do
         required = required_fields(File.read!(path))
 
@@ -271,13 +373,24 @@ defmodule GameServer.ApiConventions do
   # policy is about what crosses the wire as JSON.
   defp live_view?(file), do: String.contains?(file, "/live/")
 
-  defp source_lines(root) do
-    for path <- ex_files(root),
+  defp source_lines(roots) do
+    for path <- ex_files(roots),
         {text, line} <- Enum.with_index(String.split(File.read!(path), "\n"), 1),
         do: {path, line, text}
   end
 
-  defp ex_files(root) do
-    Path.wildcard(Path.join(root, "**/*.ex"))
+  defp ex_files(roots) when is_list(roots) do
+    roots
+    |> Enum.flat_map(fn root ->
+      # A root may itself live under deps/ (core/web pulled into a host), but
+      # anything *nested* below a root - a plugin's own deps/_build - is
+      # third-party code and not ours to lint.
+      for path <- Path.wildcard(Path.join(root, "**/*.ex")),
+          rest = String.trim_leading(path, root),
+          not String.contains?(rest, "/deps/"),
+          not String.contains?(rest, "/_build/"),
+          do: path
+    end)
+    |> Enum.uniq()
   end
 end

apps/game_server_core/lib/game_server/content.ex

@@ -403,7 +403,7 @@ defmodule GameServer.Content do
         post ->
           case render_markdown_file(post.path, "blog") do
             nil -> nil
-            html -> strip_first_h1(html)
+            html -> html |> strip_first_h1() |> strip_lede_paragraph(post.excerpt)
           end
       end
     end)
@@ -765,6 +765,33 @@ defmodule GameServer.Content do
     Regex.replace(~r/<h1>.*?<\/h1>\s*/s, html, "", global: false)
   end
 
+  # The show page renders the excerpt as a lede above the body, and the excerpt
+  # *is* the body's first paragraph — so that paragraph is dropped here or every
+  # post opens by repeating itself. Only an exact match is removed; an edited
+  # opening paragraph stays.
+  defp strip_lede_paragraph(html, excerpt) when is_binary(excerpt) and excerpt != "" do
+    case Regex.run(~r/\A\s*<p>(.*?)<\/p>\s*/s, html) do
+      [full, text] ->
+        if normalize_text(text) == normalize_text(excerpt) do
+          String.replace(html, full, "", global: false)
+        else
+          html
+        end
+
+      _ ->
+        html
+    end
+  end
+
+  defp strip_lede_paragraph(html, _excerpt), do: html
+
+  defp normalize_text(text) do
+    text
+    |> String.replace(~r/<[^>]+>/, "")
+    |> String.replace(~r/\s+/, " ")
+    |> String.trim()
+  end
+
   # Pill tag definitions: [tag] → {css_class_suffix, display_label}
   @changelog_tags %{
     "fix" => {"fix", "Fix"},

apps/game_server_core/lib/mix/tasks/gamend.api.lint.ex

@@ -23,7 +23,8 @@ defmodule Mix.Tasks.Gamend.Api.Lint do
     {"R5-path-underscore", "A route path contains a hyphen"},
     {"R6-schema-nullable", "An OpenAPI string field declares `nullable: true`"},
     {"R7-meta-helper", "A controller builds pagination meta by hand"},
-    {"R8-page-params", "A controller reads page params without Pagination.params/1"}
+    {"R8-page-params", "A controller reads page params without Pagination.params/1"},
+    {"R9-doc-route", "A guide/spec documents an API route that does not exist"}
   ]
 
   @impl true

apps/game_server_web/config/test.exs

@@ -77,6 +77,12 @@ config :game_server_web, GameServerWeb.Plugs.RateLimiter, enabled: false
 # keep logging after the test task itself is done.
 config :game_server_core, GameServer.Accounts.StalePresenceSweeper, enabled: false
 
+# Run GameServer.Async side effects inline so assertions observe them without
+# racing, and so a fire-and-forget task can't outlive the test's DB sandbox
+# owner (that surfaced as "client #PID exited" Exqlite disconnects). Kept in
+# sync with the root config/test.exs, which only applies to umbrella runs.
+config :game_server_core, async_inline: true
+
 # Jobs run inline on demand in tests (no queues/plugins/cron). Kept in sync with
 # the root config/test.exs.
 config :game_server_core, Oban, testing: :manual

apps/game_server_web/test/game_server_web/controllers/api/v1/admin/economy_controller_test.exs

@@ -81,7 +81,7 @@ defmodule GameServerWeb.Api.V1.Admin.EconomyControllerTest do
     assert [%{"item" => "potion", "quantity" => 3}] = items["data"]
   end
 
-  test "admin consume-item refuses to overdraw", %{conn: conn, target: target} do
+  test "admin consume_item refuses to overdraw", %{conn: conn, target: target} do
     conn =
       post(conn, "/api/v1/admin/economy/consume_item", %{
         user_id: target.id,

apps/game_server_web/test/game_server_web/controllers/api/v1/admin/icon_upload_test.exs

@@ -9,7 +9,6 @@ defmodule GameServerWeb.Api.V1.Admin.IconUploadTest do
 
   use GameServerWeb.ConnCase, async: false
 
-  alias GameServer.Accounts
   alias GameServer.Accounts.User
   alias GameServer.AccountsFixtures
   alias GameServer.Leaderboards

apps/game_server_web/test/game_server_web/controllers/api/v1/tournament_controller_test.exs

@@ -155,7 +155,7 @@ defmodule GameServerWeb.Api.V1.TournamentControllerTest do
            |> json_response(404)
   end
 
-  test "bracket, standings and my-match after a draw", %{
+  test "bracket, standings and my_match after a draw", %{
     auth_conn: auth_conn,
     conn: conn,
     user: user,

blog/2026-07-06-settings-storage-jobs.md

@@ -0,0 +1,32 @@
+# Ops: Settings, Storage, Jobs, Retention
+
+Added one library settings where every env var name is derived from code. Added object storage that uses both local disk and S3/R2 API. Updated the background jobs to use Oban, and retention for every unbounded table.
+
+## Settings
+
+Every setting the server understands is now *declared* in code.
+
+```elixir
+setting :min_password_length, :integer,
+  default: 8,
+  doc: "Minimum password length."
+```
+
+Settings are `required`, `warn` or `optional`.
+
+![](ops/settings.png)
+
+## Object storage
+
+Avatars and icons go through one storage facade with two backends: `local disk` and any `S3-compatible` service. Everything is inspectable in admin:
+
+![](ops/storage.png)
+
+## Jobs and retention
+
+Background work — push fan-out, mailers, webhooks, pruning — runs on Oban, with the full dashboard mounted at `/admin/oban`:
+
+![](ops/oban.png)
+
+- [Settings reference](https://gamend.appsinacup.com/docs/setup)
+- [Github](https://github.com/appsinacup/game_server)

blog/2026-07-10-economy-and-inventory.md

@@ -0,0 +1,20 @@
+# Economy: Wallets, Ledger, Inventory
+
+Virtual currencies with an append-only ledger, an item inventory, and payment providers (Stripe, Google Play, App Store, Steam) that grant entitlements server-side.
+
+## Wallets and the ledger
+
+A user has one wallet per currency, and every movement is a ledger row with a reason.
+
+```elixir
+Economy.grant(user_id, "gold", 100, reason: "match_reward")
+
+case Economy.spend(user_id, "gold", 30, reason: "store_purchase") do
+  {:ok, wallet} -> deliver_item(user_id)
+  {:error, :insufficient_funds} -> :nope
+end
+```
+
+![](economy/wallets.png)
+
+- [Github](https://github.com/appsinacup/game_server)