Wire the app like the boilerplate: door, queue, schedules, eight tabs

app/main.py assembles it in the boilerplate's order, auth.connect first,
then the queue with the scheduler and the pages. TABS is Roles,
Applications, Agents, Companies, Jobs, Schedules, Messages and Account:
the alpha page's three views become templates on the boilerplate's
base.html, driven by static/roles.js (the old app.js) through api() and
toasts.js, over the unchanged JSON routes. Companies lists every board with
its open roles and the affinity control. A 422 is one sentence, so a toast
never reads [object Object].

Config takes the boilerplate's shape: APP_CONFIG or config.yaml, a missing
file is the defaults, an unknown key is an error. roles.yaml is gone;
config.yaml is the committed default and carries the starter agents.

pull is now a job that asks for the pull cascade, because a schedule
enqueues a job kind; its default schedule, every 6h, is declared beside it
in app/jobs/cascade.py. pull_batch's targets are keyword-only so the Jobs
tab offers no batch button. `app worker` is the boilerplate's; `app job`
still drains a queue of its own and fires no schedules.

test_coupling holds pipeline, auth and desk apart (desk may import
pipeline) and plugins to desk; test_architecture keeps app's layers, now
with main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-23 12:48:12 +02:00
1 parent 24508dd6fc
commit 59a301c351
42 files changed
+2407 -998

No files matched your search

+11 -6
View File
@@ -1,10 +1,12 @@
"""The package boundaries, held as a test rather than as a convention.
Adapted from news/tests/test_architecture.py. One tree of our own, `app`,
and two external ones, `desk` and `pipeline`, imported from ../news.
and three copied ones: `pipeline` and `auth` from the boilerplate, `desk` from
news. Which of those may import which is `tests/test_coupling.py`'s rule; this
file holds `app`'s own layers.
1. **Direction.** Within `app`, a package imports only from packages below
it in `LAYERS`. `desk` and `pipeline` may be imported by any of them.
it in `LAYERS`. `desk`, `pipeline` and `auth` may be imported by any of them.
2. **Doors.** From outside a package, only `<tree>.<package>` is imported, and
only names it lists in `__all__`. `desk.tools` has no door of its own, so
there the door is the tool: `desk.tools.<tool>`, one level, no deeper.
@@ -25,10 +27,11 @@ import pytest
ROOT = Path(__file__).resolve().parents[1]
#: Bottom to top. `cli` is the entry point and may reach anything.
LAYERS = ["models", "config", "storage", "jobs", "web", "cli"]
#: Bottom to top. `main` assembles the app from everything below it; `cli`
#: and `__main__` are the entry points and may reach anything.
LAYERS = ["models", "config", "storage", "jobs", "web", "main", "cli", "__main__"]
APP = "app"
EXTERNAL = {"desk", "pipeline"}
EXTERNAL = {"desk", "pipeline", "auth"}
TREES = {APP} | EXTERNAL
@@ -142,7 +145,9 @@ def test_the_rules_catch_what_they_are_for() -> None:
assert plugin_violations("from desk.sources.base import Source")
assert not plugin_violations("from desk.sources import Source, Item")
assert direction_violations("storage", "from app.web import create_app")
assert direction_violations("storage", "from app.web import TABS")
assert direction_violations("web", "from app.main import create_app")
assert not direction_violations("main", "from app.web import pages_router")
assert direction_violations("storage", "from app import jobs")
assert not direction_violations("jobs", "from app.storage import Store")
assert not direction_violations("models", "from pipeline import job")
+13 -8
View File
@@ -1,10 +1,13 @@
"""The coupling rule, held by reading the imports.
`pipeline/` and `auth/` import nothing from `app/` and nothing from each
other. `app/` imports both. That is what makes each of them copyable on its
own into a project that has never heard of this one -- and it is exactly the
rule that breaks quietly, one convenient import at a time, until the folder is
a port rather than a copy.
The boilerplate's test, with roledesk's two extra folders. `pipeline/`,
`auth/` and `desk/` import nothing from `app/` and nothing from each other,
except that `desk/` is built on `pipeline/`, as it is in news. `plugins/`
imports `desk/` and nothing else, since a plugin is app-agnostic. `app/`
imports all of them. That is what keeps each copied folder a copy that can be
refreshed from its source, and it is the rule that breaks quietly, one
convenient import at a time, until the folder is a port rather than a copy.
`tests/test_architecture.py` holds `app/`'s own layers.
Read with `ast` rather than grepped: a string containing the word `app`, or a
line in a docstring showing what an app would write, is not an import, and a
@@ -21,10 +24,12 @@ import pytest
ROOT = Path(__file__).resolve().parent.parent
#: The module folders and what each may not reach for. Listed rather than
#: derived so that adding a fourth folder is a decision, not an accident.
#: derived so that adding a folder is a decision, not an accident.
FORBIDDEN = {
"pipeline": ("app", "auth"),
"auth": ("app", "pipeline"),
"pipeline": ("app", "auth", "desk", "plugins"),
"auth": ("app", "pipeline", "desk", "plugins"),
"desk": ("app", "auth", "plugins"),
"plugins": ("app", "pipeline", "auth"),
}
+1 -1
View File
@@ -41,7 +41,7 @@ def test_there_are_scripts_to_check():
def test_pyproject_packages_the_module_folders():
data = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
include = data["tool"]["setuptools"]["packages"]["find"]["include"]
for pattern in ("app*", "pipeline*", "auth*"):
for pattern in ("app*", "pipeline*", "auth*", "desk*"):
assert pattern in include, f"{pattern} is missing: an install would leave it out"
+22 -7
View File
@@ -17,7 +17,7 @@ if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
from desk.models import Item # noqa: E402
from pipeline import FINAL, TASKS, JobQueue, Jobs, RunContext # noqa: E402
from pipeline import FINAL, SCHEDULES, TASKS, JobQueue, Jobs, RunContext # noqa: E402
from plugins.ats import ATSSource # noqa: E402
from app.config import AgentSeed, Config # noqa: E402
from app.jobs import cascade, embed, score # noqa: E402
@@ -266,13 +266,13 @@ def test_starter_agents_are_imported_once(store: Store, tmp_path: Path) -> None:
def test_the_shipped_starter_agents_validate() -> None:
from app import config as config_mod
names = [a.name for a in config_mod.load(ROOT / "roles.yaml").agents]
names = [a.name for a in config_mod.load(ROOT / "config.yaml").agents]
assert names == ["Berlin backend", "Remote EU stretch"]
# ---------------------------------------------------------------- cascade
def test_the_pull_cascade_runs_extract_embed_then_score(
def test_the_pull_job_runs_pull_extract_embed_then_score(
store: Store, config: Config, fake: FakeEmbedder, tmp_path: Path,
monkeypatch: pytest.MonkeyPatch) -> None:
store.add_subscription("ats", "greenhouse:acme", label="Acme", company="Acme",
@@ -292,19 +292,34 @@ def test_the_pull_cascade_runs_extract_embed_then_score(
queue = JobQueue(Jobs(tmp_path / "roledesk.db"), config, store,
workers={"cpu": 1, "http": 1, "llm": 1})
task_id = queue.start_task(TASKS["pull"]())
# The `pull` job, which is what the schedule fires: its own work is to ask
# for the chain, which then runs to its end in the same drain.
started = queue.enqueue("pull")
queue.drain(timeout=60)
cascade_id = queue.jobs.of_task(task_id)[0].cascade_id
jobs = sorted(queue.jobs.of_cascade(cascade_id), key=lambda j: j.id)
assert started is not None and queue.jobs.get(started.id).state == "done" # type: ignore[union-attr]
batch = queue.jobs.last("pull_batch")
assert batch is not None
jobs = sorted(queue.jobs.of_cascade(batch.cascade_id), key=lambda j: j.id)
stages = [j.result.get("task") for j in jobs if j.kind == FINAL]
assert stages == list(cascade.CASCADES["pull"])
work = [j.kind for j in jobs if j.kind != FINAL]
assert work == ["pull_batch", "embed", "score"], "extract is off, so it finds nothing"
# The `pull` job and the chain it asked for are one cascade, so the Jobs
# tab shows a scheduled pull as one run. Extract is off and finds nothing.
assert work == ["pull", "pull_batch", "embed", "score"]
assert all(j.state == "done" for j in jobs)
assert len(store.scores(agent.id)) == 1
def test_pull_is_a_job_on_a_six_hour_schedule_and_the_stages_are_tasks() -> None:
"""A schedule enqueues a job kind, so `pull` is a job; were it a task too,
the Jobs tab would draw two `pull` buttons."""
assert "pull" not in TASKS
assert {"extract", "embed", "score"} <= set(TASKS)
assert SCHEDULES["pull"].kind == "pull"
assert SCHEDULES["pull"].cadence == "every 6h"
def test_follows_walks_the_cascade_and_stops_at_its_end() -> None:
assert cascade.follows("pull", "pull") == "extract"
assert cascade.follows("pull", "extract") == "embed"
+85 -14
View File
@@ -1,4 +1,4 @@
"""The JSON API the page calls, against a temp database and FastAPI's
"""The tabs and the JSON API they call, against a temp database and FastAPI's
TestClient. No network — nothing here touches an ATS host or the queue's own
worker beyond starting and stopping it with the app."""
@@ -12,9 +12,12 @@ import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from desk.models import Item
from app.config import Config, ServerConfig
from app.main import create_app
from app.storage import Store
from app.web.app import create_app
from app.web import TABS
from auth import AuthConfig
from desk.models import Item
class Clock:
@@ -41,10 +44,10 @@ def posting(source_id: str = "1", **raw: object) -> Item:
@pytest.fixture
def app(tmp_path: Path) -> FastAPI:
db = tmp_path / "roledesk.db"
config_path = tmp_path / "roles.yaml"
config_path.write_text(f"database: {db.as_posix()}\n", encoding="utf-8")
return create_app(str(config_path))
"""The database in `tmp_path` and the config passed in, so a test never
touches `roledesk.db` and two tests never share a jobs table."""
return create_app(Config(server=ServerConfig(host="127.0.0.1", port=0),
database=tmp_path / "roledesk.db"))
@pytest.fixture
@@ -195,14 +198,82 @@ def test_set_status_validates_and_writes_an_event(
json={"status": "applied"}).status_code == 404
# --------------------------------------------------------------------- page
# -------------------------------------------------------------------- tabs
def test_index_renders_the_shell(client: TestClient) -> None:
res = client.get("/")
assert res.status_code == 200
assert "roledesk" in res.text
assert 'id="roles-list"' in res.text
assert "<desk-jobs>" in res.text
def test_every_tab_renders_with_the_whole_nav(client: TestClient) -> None:
assert [t.label for t in TABS] == ["Roles", "Applications", "Agents", "Companies",
"Jobs", "Schedules", "Messages", "Account"]
for tab in TABS:
res = client.get(tab.path)
assert res.status_code == 200, f"{tab.path} answered {res.status_code}"
assert "roledesk</title>" in res.text
for other in TABS:
assert f">{other.label}</a>" in res.text
def test_each_roledesk_tab_is_a_shell_for_roles_js(client: TestClient) -> None:
for path, container in [("/", 'id="roles-list"'),
("/applications", 'id="applications-list"'),
("/agents", 'id="agents-list"'),
("/companies", 'id="companies-list"')]:
page = client.get(path).text
assert container in page and "/static/roles.js" in page
# toasts.js before app.js before the page's own script: `api()` needs
# `window.toast`, and roles.js needs `api()`.
assert page.index("toasts.js") < page.index("app.js") < page.index("roles.js")
assert "ROLEDESK_STATUSES" in client.get("/applications").text
assert client.get("/static/roles.js").status_code == 200
def test_the_modules_bring_their_own_elements(client: TestClient) -> None:
assert "<desk-jobs>" in client.get("/jobs").text
assert "<desk-schedules>" in client.get("/schedules").text
assert "<auth-account>" in client.get("/account").text
def test_pull_is_declared_every_six_hours(client: TestClient) -> None:
rows = {r["name"]: r for r in client.get("/api/schedules").json()}
assert rows["pull"]["kind"] == "pull"
assert rows["pull"]["cadence"] == "every 6h"
assert rows["pull"]["enabled"] is True and rows["pull"]["unknown"] is False
def test_the_jobs_tab_offers_pull_once_and_no_batch(client: TestClient) -> None:
"""A subset rather than the list: `pipeline/tests` registers kinds of its
own into the same global `JOBS` when the whole suite runs."""
kinds = [k["kind"] for k in client.get("/api/jobs/kinds").json()]
assert {"embed", "extract", "pull", "score"} <= set(kinds)
assert kinds.count("pull") == 1
assert not {"pull_batch", "extract_batch", "advance"} & set(kinds)
def test_an_error_is_one_sentence(client: TestClient) -> None:
"""`api()` toasts `detail` as it is, so a 422 is a sentence, not a list."""
res = client.post("/api/agents", json={"name": "Bad",
"gates": [{"field": "salary", "values": [1]}]})
assert res.status_code == 422
assert "gates.0.field" in res.json()["detail"]
missing = client.get("/nothing-here")
assert missing.status_code == 404 and "text/html" in missing.headers["content-type"]
def test_health_is_open_and_reads_the_store(client: TestClient) -> None:
assert client.get("/health").json() == {"ok": True, "open_roles": 0}
def test_a_locked_app_shuts_every_tab_and_the_api(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("APP_PASSWORD", "open-sesame-please")
config = Config(server=ServerConfig(host="127.0.0.1", port=0),
database=tmp_path / "locked.db", auth=AuthConfig(enabled="always"))
with TestClient(create_app(config), follow_redirects=False) as locked:
for tab in TABS:
assert locked.get(tab.path).status_code == 303
assert locked.get("/api/roles").status_code == 401
assert locked.get("/health").status_code == 200
signed_in = locked.post("/login", json={"password": "open-sesame-please"})
assert signed_in.status_code == 200
assert locked.get("/api/roles").status_code == 200
# ------------------------------------------------------------------ agents