@escape-game-over/atlas 0.1.1

package/src/project.ts

@@ -0,0 +1,249 @@
+import type { AnalyticsSettings } from "./analytics/index.ts";
+import type {
+    LocaleMetaOverride,
+    LocaleNotEnabled,
+    LocalesOf,
+    RoutingConfig,
+    SiteConfigShape,
+} from "./config.ts";
+import type {
+    BaseCatalog,
+    MessageOverlayKeys,
+    OverrideCatalog,
+    ValidateOverrideCatalog,
+} from "./i18n/define.ts";
+import type { SiteIcon, SiteVerification, ThemeColor } from "./meta/index.ts";
+import type {
+    RouteOverlayKeys,
+    RouteOverlayShape,
+    RouteOverrideMap,
+    RouteRegistry,
+} from "./routes/define.ts";
+import type { NoExcessKeys, StringKeys } from "./types.ts";
+import type { HttpsUrl, ValidSiteUrl } from "./url.ts";
+
+/**
+ * One deployment's overlay: everything that differs between sites built from the
+ * same template *and that lib needs to do its job*.
+ *
+ * Anything lib does not use — a company name, contact details — is not declared
+ * here. A project exports those separately, typed by the template's own
+ * contract, so lib never carries data it cannot reason about.
+ */
+export interface ProjectInput<L extends string, Routes> {
+    /**
+     * Absolute origin, e.g. `https://example.com`.
+     *
+     * No trailing slash — which the type cannot say, since a template literal
+     * cannot express "does not end in". `ValidSiteUrl` in `defineProject`
+     * checks it where the URL is written, and `createSite` throws on it at
+     * build time for a project object assembled some other way.
+     *
+     * The scheme *is* stated here, and the two together read better than either
+     * alone: the constraint names the offending literal, and `ValidSiteUrl`
+     * still supplies the sentence explaining it.
+     */
+    readonly url: HttpsUrl;
+    /**
+     * The publisher's human-readable name, for `og:site_name`.
+     *
+     * Site-level, not per page: it is identical on every page, so stating it
+     * once here beats restating it at every `metaFor` call.
+     */
+    readonly siteName: string;
+    /** `@handle` of the site, for `twitter:site`. Also identical everywhere. */
+    readonly twitterSite?: string;
+    /**
+     * The site's icon: one square asset, used for `icon` and `apple-touch-icon`.
+     *
+     * Site-wide and required: search engines use one favicon per hostname, read
+     * from the home page, so a per-page icon would change the browser tab and
+     * nothing else.
+     */
+    readonly icon: SiteIcon;
+    /**
+     * Ownership tokens from Search Console, Bing Webmaster Tools and the like.
+     *
+     * Per project rather than per site: each deployment is its own property in
+     * those tools, verified by whoever owns that domain.
+     */
+    readonly verification?: SiteVerification;
+    /**
+     * What this deployment records about its own traffic.
+     *
+     * Per project, and beside `verification` because it is the same kind of
+     * thing: one property in one third-party dashboard, identified by an id
+     * that must not be shared with another deployment.
+     *
+     * lib builds the tags — the host, the script names and the attribute
+     * spellings are all derived from these settings and from `url` above, so a
+     * consuming repo states an id and nothing else. See `analytics.ts`.
+     */
+    readonly analytics?: AnalyticsSettings;
+    /**
+     * Tints the browser UI. One value, or one per `prefers-color-scheme`.
+     *
+     * Required: the browser picks its own chrome colour otherwise, and it will
+     * not match your page.
+     */
+    readonly themeColor: ThemeColor;
+    /** Which colour schemes the pages support, e.g. `"light"`, `"dark light"`. */
+    readonly colorScheme?: string;
+    /**
+     * Which of the site's locales this project publishes.
+     *
+     * A selection, not an override: the site config declares which languages
+     * exist at all, and a project picks from them. Naming one it does not
+     * declare is a compile error.
+     */
+    readonly enabledLocales: readonly L[];
+    /**
+     * Replaces parts of the site's `defaultRouting` for this project.
+     *
+     * Every `override*` field below is named for what it does to the template's
+     * defaults, because a project file is read alongside them and `routing: {…}`
+     * reads like the whole truth when it is only a patch.
+     */
+    readonly overrideRouting?: Partial<RoutingConfig<L>>;
+    /** Restates a locale's label. Its writing direction is not overridable. */
+    readonly overrideLocaleMeta?: Readonly<
+        Partial<Record<L, LocaleMetaOverride>>
+    >;
+    /**
+     * Copy overrides: any subset of keys, any subset of locales.
+     *
+     * **Required, and `{}` is the answer for a deployment that overrides
+     * nothing.** Unlike the two fields above, which are optional.
+     *
+     * The reason is not that an absent overlay and an empty one read
+     * differently — they do, and that argument would make all four of these
+     * required. It is that these two are what the type machinery *computes
+     * from*: the route ids a project builds, the message keys it may override,
+     * and the locales each may be written for are all read off these fields,
+     * at seven sites in this file. Optional means `undefined` flowing into
+     * every one of them, `NonNullable<>` at each — see `overrideRouting` above,
+     * the one optional field that is read, for what that looks like — and an
+     * inference that widens where it should narrow.
+     *
+     * `{}` costing two characters is the price of the ids downstream being
+     * exact. It also happens to read as a statement, which is a bonus rather
+     * than the argument.
+     */
+    readonly overrideMessages: OverrideCatalog<L>;
+    /** Slug retranslations and page on/off switches. See `overrideMessages`. */
+    readonly overrideRoutes: RouteOverrideMap<L, Routes>;
+}
+
+/**
+ * Declares one deployment, validated against the site config and base data.
+ *
+ * Everything is inferred from the values passed in, so a project file writes no
+ * type arguments at all.
+ *
+ * Enforced at compile time:
+ *  - `url` must not end with a slash;
+ *  - `overrideMessages` keys must exist in the default catalog, and must keep
+ *    the default message's `{placeholders}`;
+ *  - `overrideRoutes` keys must be real route ids;
+ *  - unknown top-level fields are rejected, so a typo cannot sit there unread;
+ *  - locales named anywhere must be ones the site ships and this project enabled.
+ */
+export function defineProject<
+    const C extends SiteConfigShape,
+    const Catalog extends BaseCatalog<LocalesOf<C>>,
+    const Routes extends RouteRegistry<LocalesOf<C>>,
+    const T extends ProjectInput<LocalesOf<C>, Routes> &
+        NoExcessKeys<T, keyof ProjectInput<LocalesOf<C>, Routes>> & {
+            readonly url: ValidSiteUrl<T["url"]>;
+            readonly overrideRouting?: {
+                readonly defaultLocale?: T["enabledLocales"][number];
+                // Against `enabledLocales` rather than the site's list: a
+                // segment spelled for a language this deployment does not
+                // publish is a word that appears in no URL it builds. Mapped
+                // over the keys written, for the reason `overrideLocaleMeta`
+                // below is.
+                readonly pageSegmentByLocale?: {
+                    readonly [K in StringKeys<
+                        NonNullable<T["overrideRouting"]>["pageSegmentByLocale"]
+                    >]: K extends T["enabledLocales"][number]
+                        ? string
+                        : LocaleNotEnabled<K>;
+                };
+            };
+            // Two separate checks on the same field: the keys must be messages
+            // the default catalog declares, and the locales inside each must be
+            // ones this project publishes. Copy written for a locale left out of
+            // `enabledLocales` is never built, so it is always a mistake — a
+            // locale removed from the list, or a project copied from another.
+            readonly overrideMessages: MessageOverlayKeys<
+                Catalog,
+                T["overrideMessages"]
+            > & {
+                readonly [K in StringKeys<T["overrideMessages"]>]: {
+                    readonly [L in StringKeys<
+                        T["overrideMessages"][K]
+                    >]: L extends T["enabledLocales"][number]
+                        ? T["overrideMessages"][K][L]
+                        : LocaleNotEnabled<L>;
+                };
+            };
+            // Shared with `defineRouteOverrides` rather than restated — see
+            // `RouteOverlayKeys` for why the two must not drift.
+            readonly overrideRoutes: RouteOverlayKeys<
+                Routes,
+                T["overrideRoutes"]
+            >;
+            // Nested, so that `dir` is rejected inside each locale's entry.
+            // Declaring the field as `Pick<LocaleMeta, "label">` is not enough:
+            // `T` is *inferred* from the literal, so a stray `dir` just becomes
+            // part of `T` and there is no fresh object for excess-property
+            // checking to fire on.
+            readonly overrideLocaleMeta?: {
+                readonly [K in StringKeys<
+                    T["overrideLocaleMeta"]
+                >]: K extends T["enabledLocales"][number]
+                    ? NoExcessKeys<
+                          T["overrideLocaleMeta"][K],
+                          keyof LocaleMetaOverride
+                      >
+                    : LocaleNotEnabled<K>;
+            };
+        },
+>(
+    // The first three are read for their types: they are how the locale union,
+    // the message keys and the route ids are inferred without type arguments.
+    _config: C,
+    _messages: Catalog,
+    _routes: Routes,
+    // Both validators sit in parameter position rather than in the constraint
+    // above. They map the *whole* override object, and a whole-object mapped
+    // type in a constraint makes one unrelated mistake fail the argument
+    // outright — TypeScript then reports at this call instead of on the line
+    // that is wrong.
+    project: T & {
+        readonly overrideMessages: ValidateOverrideCatalog<
+            T["overrideMessages"],
+            Catalog,
+            LocalesOf<C>
+        >;
+        // The same alias `defineRouteOverrides` uses, so writing the overlay
+        // inline is never the weaker option.
+        readonly overrideRoutes: RouteOverlayShape<Routes, T["overrideRoutes"]>;
+    }
+): T {
+    // Checked at runtime as well as in the type, because the type is not always
+    // what fails first. An Astro config is *evaluated* before `astro check`
+    // runs, so a project file missing one of these reaches `mergeCatalog` and
+    // throws there — a stack trace inside lib, naming a variable the reader
+    // never wrote, for a field the compiler would have named precisely.
+    //
+    // Two lines to turn that back into the error it already was.
+    for (const field of ["overrideMessages", "overrideRoutes"] as const) {
+        if (project[field] === undefined) {
+            throw new Error(
+                `Project "${project.siteName}" declares no ${field}. It is required even when nothing is overridden — write \`${field}: {}\`, which is what the type asks for and what tells a reader the shared ${field === "overrideMessages" ? "copy" : "route table"} is used as it is.`
+            );
+        }
+    }
+    return project;
+}

package/src/redirects.ts

@@ -0,0 +1,266 @@
+/**
+ * Redirects: old URLs that must keep working after the site moved on.
+ *
+ * The source is always a path on this site, because a redirect you serve is one
+ * you are asked for — a host you do not control is not yours to redirect. The
+ * target is either another page of this site, named by route id so it is checked
+ * and its URL derived, or an absolute `https://` URL somewhere else.
+ *
+ * `site.redirects()` returns the resolved rules *and* a rendered file, the way
+ * `sitemap()` returns entries and files. A consumer that only wants the data —
+ * to feed a host with its own format — reads `rules`; one deploying to a static
+ * host writes `file` and is done.
+ */
+
+import type { GeneratedFile } from "./file.ts";
+import type { PublicFilePath } from "./files.ts";
+import {
+    type HttpsUrl,
+    joinUrl,
+    type UrlPath,
+    type ValidHttpsUrl,
+} from "./url.ts";
+
+/**
+ * Whether a redirect is a move or a detour.
+ *
+ * Named rather than numbered, and required rather than defaulted, because it is
+ * a decision with consequences in both directions and no safe default. A
+ * permanent redirect hands the old URL's search standing to the new one and is
+ * cached by browsers more or less forever — getting it wrong on a campaign URL
+ * means visitors who cannot be sent back. A temporary one transfers nothing, so
+ * using it for a real move quietly throws away everything the old URL earned.
+ *
+ * Two values, not four. The HTTP vocabulary also has `307` and `308`, which
+ * differ from `302` and `301` only by forbidding the method to change from POST
+ * to GET — a distinction a static site of `GET` requests can never exercise.
+ * Offering all four would mean three ways to spell the same outcome and one
+ * chance to pick the wrong one for a reason that does not apply here.
+ */
+export type RedirectKind = "permanent" | "temporary";
+
+/** The wire status each kind is served with. */
+const STATUS: Readonly<Record<RedirectKind, RedirectStatus>> = {
+    permanent: 301,
+    temporary: 302,
+};
+
+/** What ends up in the file. `RedirectKind` is what a consumer writes. */
+export type RedirectStatus = 301 | 302;
+
+/** Resolves a rule's kind to the status it is served with. */
+export function statusFor(kind: RedirectKind): RedirectStatus {
+    return STATUS[kind];
+}
+
+/**
+ * A path on *this* site, from the root. Never a host.
+ *
+ * `UrlPath` under a name that says whose site it is: a redirect source has to
+ * be local, since a host you do not control is not yours to redirect. Aliased
+ * rather than re-declared, so the two cannot drift into different shapes.
+ */
+export type SitePath = UrlPath;
+
+/**
+ * Somewhere else entirely. `https` only — a redirect to `http` is a downgrade.
+ *
+ * `HttpsUrl` under a name that says whose site it is *not*, aliased for the
+ * same reason `SitePath` is: spelling the pattern again here would be a second
+ * definition of "acceptable URL", and `ValidHttpsUrl` — which is what actually
+ * reports the mistake — is written against the first one.
+ */
+export type ExternalUrl = HttpsUrl;
+
+/**
+ * Rejects an external target that is not `https://`, naming it.
+ *
+ * Applied to the rules array in parameter position, so a bad URL reports on its
+ * own line rather than as the whole array failing to match. The check itself is
+ * `ValidHttpsUrl`, shared with the site origin — one idea of an acceptable URL,
+ * stated once.
+ */
+export type ValidateRedirectTargets<Rules> = {
+    readonly [K in keyof Rules]: Rules[K] extends {
+        readonly to: infer To extends string;
+    }
+        ? {
+              // Every key carried through, and only `to` rewritten. Declaring
+              // just `to` would make the rest read as excess properties.
+              readonly [P in keyof Rules[K]]: P extends "to"
+                  ? ValidHttpsUrl<To>
+                  : Rules[K][P];
+          }
+        : Rules[K];
+};
+
+/**
+ * Where a redirect points: a page of this site, or an external URL.
+ *
+ * The internal form names a route rather than spelling a path, so it is checked
+ * against what this project builds and its URL is derived — a redirect cannot
+ * outlive the page it points at, or miss a slug that was retranslated. The
+ * locale is optional and defaults to the site's own, since an old URL usually
+ * predates translation.
+ */
+export type RedirectTarget<Id extends string, L extends string> =
+    | ExternalUrl
+    | { readonly route: Id; readonly locale?: L }
+    /**
+     * A file served verbatim from `public/` — a PDF, a spreadsheet.
+     *
+     * Its own shape rather than a bare path, so it cannot be confused with a
+     * route: a route target is checked against the pages this project builds,
+     * and lib has no way to see what sits in `public/`. What it can do is refuse
+     * to guess — a path here is taken as given, and narrowing it is the
+     * project's job. The `PublicFile` union that `publicFiles()` generates is
+     * exactly that narrowing.
+     */
+    | { readonly file: PublicFilePath };
+
+export interface RedirectRule<Id extends string, L extends string> {
+    /** The old path, exactly as it was requested. */
+    readonly from: SitePath;
+    readonly to: RedirectTarget<Id, L>;
+    /**
+     * Whether this is a move or a detour. Required — see `RedirectKind`.
+     *
+     * Stated on every rule for the same reason `robots` is stated on every
+     * page: the wrong answer is invisible in the output, so inheriting one is
+     * how a mistake gets shipped without anyone choosing it.
+     */
+    readonly kind: RedirectKind;
+}
+
+/** One rule with its target resolved to a URL or path, ready to serve. */
+export interface ResolvedRedirect {
+    readonly from: string;
+    readonly to: string;
+    readonly status: RedirectStatus;
+}
+
+/** What the Cloudflare renderer needs beyond the rules themselves. */
+export interface CloudflareRedirectsOptions {
+    readonly siteUrl: HttpsUrl;
+    /** Filename it is served under. Defaults to `_redirects`. */
+    readonly name?: string;
+}
+
+/**
+ * Cloudflare Pages honours the first 2000 rules and drops the rest in silence.
+ *
+ * Not an option: it is a fact about the host this renderer is named for, not a
+ * preference. Exposing it would only let a caller supply a number that is not
+ * the real one, and the failure it guards against — redirects that quietly stop
+ * working because they sit at the bottom of a long file — is exactly the kind
+ * nobody goes looking for.
+ */
+const CLOUDFLARE_RULE_LIMIT = 2000;
+
+export interface RedirectsInput {
+    readonly rules: readonly ResolvedRedirect[];
+    /**
+     * Every path this build actually serves.
+     *
+     * Used to reject a redirect that shadows a real page. Hosts disagree about
+     * which of the two wins — some serve the file and leave the rule dead,
+     * while Cloudflare Pages states that redirects are followed whether or not
+     * an asset matches, which instead makes the *page* unreachable. Since the
+     * outcome is a coin toss decided somewhere the build cannot see, and one
+     * side of it silently deletes a page, both are rejected here.
+     */
+    readonly builtPaths: ReadonlySet<string>;
+}
+
+const REDIRECTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+
+/**
+ * Checks a set of resolved rules and hands them back.
+ *
+ * Separate from rendering because these are facts about the *set* — a duplicate
+ * source, a source that is already a page, a rule pointing at itself — and hold
+ * whatever format the rules end up in. A consumer feeding a host with its own
+ * redirect syntax gets the same guarantees as one writing `_redirects`.
+ */
+export function buildRedirects(
+    input: RedirectsInput
+): readonly ResolvedRedirect[] {
+    const seen = new Map<string, string>();
+
+    for (const rule of input.rules) {
+        if (!rule.from.startsWith("/")) {
+            throw new Error(
+                `Redirect source "${rule.from}" must be a path beginning with "/". A redirect answers a request to this site, so its source is never a host.`
+            );
+        }
+        // A source that is not the canonical form of its own URL. Hosts differ
+        // on whether they strip a trailing slash before matching or treat the
+        // two as one URL, and on either reading this rule is unreliable: at
+        // best it duplicates the slash-free form, at worst it never fires. lib
+        // builds no such path, so nothing legitimate produces one.
+        if (rule.from.length > 1 && rule.from.endsWith("/")) {
+            throw new Error(
+                `Redirect source "${rule.from}" ends with a slash. Write it as "${rule.from.slice(0, -1)}": a host that strips the slash before matching would never reach this rule.`
+            );
+        }
+        if (rule.from.startsWith("//")) {
+            throw new Error(
+                `Redirect source "${rule.from}" starts with "//", which browsers read as a protocol-relative host rather than a path.`
+            );
+        }
+
+        const clash = seen.get(rule.from);
+        if (clash !== undefined) {
+            throw new Error(
+                `Two redirects both claim "${rule.from}" (to "${clash}" and "${rule.to}"). Only the first would ever fire.`
+            );
+        }
+        seen.set(rule.from, rule.to);
+
+        if (input.builtPaths.has(rule.from)) {
+            throw new Error(
+                `Redirect source "${rule.from}" is a page this site builds. One of the two wins and the other is dead, and which one depends on the host: Cloudflare follows redirects whether or not an asset matches, so there the page becomes unreachable. Remove the rule, or the page.`
+            );
+        }
+        if (rule.from === rule.to) {
+            throw new Error(
+                `Redirect "${rule.from}" points at itself, which is a loop.`
+            );
+        }
+    }
+
+    return input.rules;
+}
+
+/**
+ * Renders resolved rules as Cloudflare Pages' `_redirects`: `from to status`,
+ * one per line. Netlify reads the same format.
+ *
+ * Named for the host on purpose. It is *one* way to serve these rules, and the
+ * rules themselves know nothing about it — a Vercel `vercel.json` or an nginx
+ * `return 301` renderer sits beside this one and takes the same input. A vaguer
+ * name would suggest there is only ever one file, which is the assumption worth
+ * not baking in.
+ */
+export function buildCloudflareRedirects(
+    redirects: readonly ResolvedRedirect[],
+    options: CloudflareRedirectsOptions
+): GeneratedFile {
+    if (redirects.length > CLOUDFLARE_RULE_LIMIT) {
+        throw new Error(
+            `${redirects.length} redirects exceeds the ${CLOUDFLARE_RULE_LIMIT} Cloudflare Pages honours. Everything past that would be dropped silently.`
+        );
+    }
+
+    const name = options.name ?? "_redirects";
+    const body = redirects
+        .map((rule) => `${rule.from} ${rule.to} ${rule.status}`)
+        .join("\n");
+
+    return {
+        name,
+        url: joinUrl(options.siteUrl, `/${name}`),
+        body: body === "" ? "" : `${body}\n`,
+        contentType: REDIRECTS_CONTENT_TYPE,
+    };
+}

package/src/robots.ts

@@ -0,0 +1,80 @@
+import type { GeneratedFile } from "./file.ts";
+import { type HttpsUrl, joinUrl } from "./url.ts";
+
+/** One `User-agent` block. */
+export interface RobotsGroup {
+    /** One agent or several, e.g. `"*"` or `["Googlebot", "Bingbot"]`. */
+    readonly userAgent: string | readonly string[];
+    readonly allow?: readonly string[];
+    readonly disallow?: readonly string[];
+    /** Seconds between requests. Ignored by Google, honoured by some others. */
+    readonly crawlDelay?: number;
+}
+
+/** How a site configures `robots.txt`. Part of `site.config.ts`. */
+export interface RobotsConfig {
+    /** Filename it is served under. Defaults to `robots.txt`. */
+    readonly name?: string;
+    /** Defaults to one group allowing everything. */
+    readonly groups?: readonly RobotsGroup[];
+}
+
+export interface RobotsInput {
+    readonly name: string;
+    readonly siteUrl: HttpsUrl;
+    /**
+     * Absolute URL of the sitemap to advertise.
+     *
+     * `robots.txt` permits several `Sitemap:` lines, but one pointing at the
+     * index is enough — the index already lists every part. Required, because a
+     * site always has a sitemap here and omitting the line would only hide it
+     * from crawlers.
+     */
+    readonly sitemap: string;
+    /** Defaults to one group allowing everything. */
+    readonly groups?: readonly RobotsGroup[];
+}
+
+const DEFAULT_GROUPS: readonly RobotsGroup[] = [
+    { userAgent: "*", allow: ["/"] },
+];
+
+/**
+ * Renders `robots.txt`.
+ *
+ * Site-wide crawl rules belong here rather than in a `robots` meta tag: a tag
+ * only speaks for the page it sits on, and a crawler has to fetch that page to
+ * read it — which is exactly what you were trying to prevent.
+ */
+export function buildRobots(input: RobotsInput): GeneratedFile {
+    const lines: string[] = [];
+
+    for (const group of input.groups ?? DEFAULT_GROUPS) {
+        const agents =
+            typeof group.userAgent === "string"
+                ? [group.userAgent]
+                : group.userAgent;
+        for (const agent of agents) {
+            lines.push(`User-agent: ${agent}`);
+        }
+        for (const path of group.allow ?? []) {
+            lines.push(`Allow: ${path}`);
+        }
+        for (const path of group.disallow ?? []) {
+            lines.push(`Disallow: ${path}`);
+        }
+        if (group.crawlDelay !== undefined) {
+            lines.push(`Crawl-delay: ${group.crawlDelay}`);
+        }
+        lines.push("");
+    }
+
+    lines.push(`Sitemap: ${input.sitemap}`);
+
+    return {
+        name: input.name,
+        url: joinUrl(input.siteUrl, `/${input.name}`),
+        body: `${lines.join("\n").trimEnd()}\n`,
+        contentType: "text/plain; charset=utf-8",
+    };
+}