feat(warmup): a curated warmup list that lives in code, not in wp-admin

[parisek]

Follow-up to #134. The scorer already has manual as a source at weight 800, but the only way to feed it is Breeze's own settings row. That makes the one curated signal in the model the one signal a project cannot version.

The problem

SignalCollector::manualKeys() reads breeze-preload-cache-urls out of breeze_get_option( 'preload_settings' ). So a curated list:

• is not in git — it cannot be reviewed, and nothing records why a URL is on it
• is wiped by a database import, silently, and the site quietly stops warming what mattered
• has to be re-entered per environment, and differs between them by accident rather than intent

Measured on sloneek while adopting #134: the site's 53 category archives scored only through the manual list. They are in no menu, are not a homepage, and their lastmod is old — so with that row emptied they fell from position 27-30 to ~2864 of 2873. That project then decided the archives are not priority, which resolved it there, but the shape of the problem is general.

The signals the kit has are homepage, menu membership and freshness. A priority page that is none of those has no way up:

• a campaign landing page deliberately not in a menu
• a deep page carrying real search traffic
• a category archive on a project where it is priority
• anything correct and finished, so its lastmod is old

Proposed shape

protected array $breeze_warmup_urls = array(
    '/blog/',
    '/cs/blog/',
    'https://example.de/blog/',
);

Entries merge into manualKeys(), so they score at the existing manual weight and need no new weight, no new tier and no ordering change.

Both forms accepted, deliberately. A relative path is what a project wants most of the time — the same code runs on ddev, on staging and on production, and an absolute URL would be silently wrong on two of the three (rejected by is_local_url(), warming nothing, reporting nothing). An absolute URL is what a project needs when the target is not on home_url()'s host at all.

Which is the case with domain-per-language

isFetchableSameHostUrl() compares against home_url()'s host and nothing else. Under WPML's domain-per-language negotiation every non-default language is on a different host, so an absolute URL for one of them is rejected today.

SignalCollector already calls wpml_active_languages, which carries each language's url, so the allowed-host set is derivable. This feature needs it, and the sitemap crawl arguably wants the same treatment — though that is a separate change and should not ride along silently.

Open question

Whether a relative path should be expanded across active languages, or taken literally. Literal is more predictable and matches what is written; expansion saves five lines per entry on a five-language site and removes the chance of forgetting one. My inclination is literal, with expansion left to a filter, but it is worth deciding before the API exists rather than after.

Not proposed

Any change to ordering, weights or the cap. This adds an input to a source that already exists.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JMYy6JHLf4mU4H4Hd47spb

[parisek]

Refined after review — resolve to a WP ID first

The owner's suggestion, and it is better than what the issue proposes above: do not take the string as the answer, resolve it and use what comes back.

The kit already has this pattern — Breadcrumb::get_global_links():

$post_id = url_to_postid( $item );
if ( $post_id ) {
    $translated_id = (int) apply_filters( 'wpml_object_id', $post_id, 'page' );
    $url = get_permalink( $translated_id );
}

Applied here it settles four things at once:

• Non-existent entries drop themselves. url_to_postid() returns 0 and the entry never enters the list — no stale URL warming a 404 on every cycle, and no maintenance ritual after content is deleted.
• The environment stops mattering. The stored value is get_permalink()'s output, so ddev, staging and production each resolve the same written entry to their own correct URL. That is what makes accepting a relative path safe rather than merely convenient.
• Domain-per-language solves itself. get_permalink() returns the language's own host, so the allowed-host set stops being something this feature has to compute.
• A typo is visible. An entry that resolves to nothing can be reported rather than silently warming nothing.

Where it does not reach, and what to do about it

url_to_postid() resolves posts and pages. It does not resolve a term archive, and a category archive was the original motivating example. So the resolution is two-stage:

1. url_to_postid() → wpml_object_id → get_permalink(). Covers pages and posts, which is most of a curated list.
2. Otherwise keep the entry as a URL, resolved against home_url() when relative, and verify it exists with one HEAD during the cron refresh. The refresh already does network I/O and is off the purge path, so the cost sits where it is affordable. An entry that does not answer 2xx/3xx is dropped, which extends "non-existent entries drop themselves" to archives without pretending url_to_postid() can see them.

Stage 2 keeps the feature honest about a real limit rather than quietly warming a dead URL forever.

🤖 Generated with Claude Code

[parisek]

Decision: literal, with expansion left as a future addition

Settled rather than deferred, because the API is about to have consumers.

Entries are taken literally. /blog/ warms /blog/ and nothing else. A project wanting five languages writes five lines.

The original proposal above was wrong, and measuring killed it

The issue floated expanding a relative path across active languages. On a real WPML site the slugs are translated, not merely prefixed:

English	Czech	Italian
/pricing/	/cs/cenik/	/it/listino-prezzi/
/lexicon/	/cs/slovnik-pojmu/	/it/glossario-di-termini/

Verified by request against a live five-language site while adopting #134. Prefix-based expansion would have produced /it/pricing/ — a 404. And since the probe drops only 404 and 410, that entry would be discarded silently: a feature that looks like it works and warms nothing.

If expansion is ever added, it goes through the ID

The resolver already does the round trip — URL to post ID to get_permalink(). Expansion is then wpml_object_id( $id, $type, false, $lang ) per active language, which returns the real translated slug instead of a guess.

It has a limit that must not be hidden: it works for posts and pages only. A term archive cannot be resolved to an ID, so those would stay literal — and a mechanism that silently does nothing for part of its input is worse than no mechanism.

Why literal now

• What is written is what happens, and a list in git can be reviewed for exactly that. Expansion hides a 5× multiplication against a 200-entry cap: one extra line could quietly eat a fifth of the budget.
• A missing language is a visible omission in a diff. A wrongly expanded URL is a silent 404.
• There is no consumer yet. The project that motivated this found it does not need a curated list at all — with category archives excluded, menu membership and homepage status carry everything inside the cap. Designing expansion with no site to show how translated slugs should behave would be guessing.

It does not paint us into a corner

An earlier note here called changing this a BC break once the API has users. That was overstated: it holds only for changing how existing entries behave. Expansion arriving as an addition — a second property, or a per-entry marker — breaks nothing. Literal-now costs no future option.

🤖 Generated with Claude Code